diff --git a/README.md b/README.md index f48cfea..136f1a5 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ the top-level `index.html` in a web browser. ## Theming -The Godot documentation uses the default ``sphinx_rtd_theme`` with many +The Godot documentation uses the default `sphinx_rtd_theme` with many [customizations](_static/) applied on top. It will automatically switch between the light and dark theme depending on your browser/OS' theming preference. diff --git a/about/complying_with_licenses.rst b/about/complying_with_licenses.rst index 833dbea..8cb8df4 100644 --- a/about/complying_with_licenses.rst +++ b/about/complying_with_licenses.rst @@ -89,7 +89,7 @@ If the game includes printed manuals, license text can be included there. Link to the license ^^^^^^^^^^^^^^^^^^^ -The Godot Engine developers consider that a link to ``godotengine.org/license`` +The Godot Engine developers consider that a link to `godotengine.org/license` in your game documentation or credits would be an acceptable way to satisfy the license terms. diff --git a/about/faq.rst b/about/faq.rst index 523873a..b42e9bf 100644 --- a/about/faq.rst +++ b/about/faq.rst @@ -204,7 +204,7 @@ Windows - Move the Godot executable to a stable location (i.e. outside of your Downloads folder), so you don't accidentally move it and break the shortcut in the future. - Right-click the Godot executable and choose **Create Shortcut**. -- Move the created shortcut to ``%LOCALAPPDATA%\Microsoft\Windows\Start Menu\Programs``. +- Move the created shortcut to `%LOCALAPPDATA%\Microsoft\Windows\Start Menu\Programs`. This is the user-wide location for shortcuts that will appear in the Start menu. You can also pin Godot in the task bar by right-clicking the executable and choosing **Pin to Task Bar**. @@ -212,29 +212,29 @@ Windows macOS ^^^^^ -Drag the extracted Godot application to ``/Applications/Godot.app``, then drag it +Drag the extracted Godot application to `/Applications/Godot.app`, then drag it to the Dock if desired. Spotlight will be able to find Godot as long as it's in -``/Applications`` or ``~/Applications``. +`/Applications` or `~/Applications`. Linux ^^^^^ - Move the Godot binary to a stable location (i.e. outside of your Downloads folder), so you don't accidentally move it and break the shortcut in the future. -- Rename and move the Godot binary to a location present in your ``PATH`` environment variable. - This is typically ``/usr/local/bin/godot`` or ``/usr/bin/godot``. +- Rename and move the Godot binary to a location present in your `PATH` environment variable. + This is typically `/usr/local/bin/godot` or `/usr/bin/godot`. Doing this requires administrator privileges, but this also allows you to - `run the Godot editor from a terminal ` by entering ``godot``. + `run the Godot editor from a terminal ` by entering `godot`. - If you cannot move the Godot editor binary to a protected location, you can - keep the binary somewhere in your home directory, and modify the ``Path=`` - line in the ``.desktop`` file linked below to contain the full *absolute* path + keep the binary somewhere in your home directory, and modify the `Path=` + line in the `.desktop` file linked below to contain the full *absolute* path to the Godot binary. - Save `this .desktop file `__ - to ``$HOME/.local/share/applications/``. If you have administrator privileges, - you can also save the ``.desktop`` file to ``/usr/local/share/applications`` + to `$HOME/.local/share/applications/`. If you have administrator privileges, + you can also save the `.desktop` file to `/usr/local/share/applications` to make the shortcut available for all users. Is the Godot editor a portable application? diff --git a/about/list_of_features.rst b/about/list_of_features.rst index 35df7db..95362d9 100644 --- a/about/list_of_features.rst +++ b/about/list_of_features.rst @@ -495,7 +495,7 @@ Internationalization - Store localization strings using `CSV ` or `gettext `. - Use localized strings in your project automatically in GUI elements or by - using the ``tr()`` function. + using the `tr()` function. - Support for right-to-left typesetting and text shaping planned in Godot 4.0. Windowing and OS integration @@ -518,7 +518,7 @@ Windowing and OS integration - Parse custom command line arguments. - `Headless/server binaries ` can be downloaded for Linux and `compiled for macOS `. - Any binary can be used without a window using the ``--no-window`` + Any binary can be used without a window using the `--no-window` `command line argument `. Mobile @@ -569,8 +569,8 @@ The editor UI can easily be extended in many ways using add-ons. layouts. - `Draggable splitter` layouts. -- Scale to multiple resolutions using the ``2d`` or ``viewport`` stretch modes. -- Support any aspect ratio using anchors and the ``expand`` stretch aspect. +- Scale to multiple resolutions using the `2d` or `viewport` stretch modes. +- Support any aspect ratio using anchors and the `expand` stretch aspect. **Theming:** diff --git a/about/release_policy.rst b/about/release_policy.rst index 0e4543a..6f9e70e 100644 --- a/about/release_policy.rst +++ b/about/release_policy.rst @@ -12,10 +12,10 @@ Godot versioning ---------------- Godot loosely follows `Semantic Versioning `__ with a -``major.minor.patch`` versioning system, albeit with an interpretation of each +`major.minor.patch` versioning system, albeit with an interpretation of each term adapted to the complexity of a game engine: -- The ``major`` version is incremented when major compatibility breakages happen +- The `major` version is incremented when major compatibility breakages happen which imply significant porting work to move projects from one major version to another. @@ -23,7 +23,7 @@ term adapted to the complexity of a game engine: running the project through a conversion tool, and then performing a number of further adjustments manually for what the tool could not do automatically. -- The ``minor`` version is incremented for feature releases which do not break +- The `minor` version is incremented for feature releases which do not break compatibility in a major way. Minor compatibility breakage in very specific areas *may* happen in minor versions, but the vast majority of projects should not be affected or require significant porting work. @@ -40,7 +40,7 @@ term adapted to the complexity of a game engine: but some testing is necessary to ensure that your project still behaves as expected in a new minor version. -- The ``patch`` version is incremented for maintenance releases which focus on +- The `patch` version is incremented for maintenance releases which focus on fixing bugs and security issues, implementing new requirements for platform support, and backporting safe usability enhancements. Patch releases are backwards compatible. @@ -53,18 +53,18 @@ term adapted to the complexity of a game engine: Updating to new patch versions is therefore considered safe and strongly recommended to all users of a given stable branch. -We call ``major.minor`` combinations *stable branches*. Each stable branch -starts with a ``major.minor`` release (without the ``0`` for ``patch``) and is +We call `major.minor` combinations *stable branches*. Each stable branch +starts with a `major.minor` release (without the `0` for `patch`) and is 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). +`3.3` Git branch). .. 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. In particular, the 3.2 stable branch received a number of new features in - 3.2.2 which would have warranted a ``minor`` version increment. + 3.2.2 which would have warranted a `minor` version increment. Release support timeline ------------------------ diff --git a/about/troubleshooting.rst b/about/troubleshooting.rst index 3e456e9..8ac637a 100644 --- a/about/troubleshooting.rst +++ b/about/troubleshooting.rst @@ -69,7 +69,7 @@ This is caused by the NVIDIA graphics driver injecting an overlay to display inf To disable this overlay on Windows, restore your graphics driver settings to the default values in the NVIDIA Control Panel. -To disable this overlay on Linux, open ``nvidia-settings``, go to **X Screen 0 > +To disable this overlay on Linux, open `nvidia-settings`, go to **X Screen 0 > OpenGL Settings** then uncheck **Enable Graphics API Visual Indicator**. The project window appears blurry, unlike the editor. @@ -97,8 +97,8 @@ The project works when run from the editor, but fails to load some files when ru This is usually caused by forgetting to specify a filter for non-resource files in the Export dialog. By default, Godot will only include actual *resources* into the PCK file. Some files commonly used, such as JSON files, are not -considered resources. For example, if you load ``test.json`` in the exported -project, you need to specify ``*.json`` in the non-resource export filter. See +considered resources. For example, if you load `test.json` in the exported +project, you need to specify `*.json` in the non-resource export filter. See `doc_exporting_projects_export_mode` for more information. On Windows, this can also be due to `case sensitivity diff --git a/community/contributing/bisecting_regressions.rst b/community/contributing/bisecting_regressions.rst index 97c6ff8..ea73a2a 100644 --- a/community/contributing/bisecting_regressions.rst +++ b/community/contributing/bisecting_regressions.rst @@ -26,7 +26,7 @@ performance regressions. Using official builds to speed up bisecting ------------------------------------------- -Before using Git's ``bisect`` command, we strongly recommend trying to reproduce +Before using Git's `bisect` command, we strongly recommend trying to reproduce the bug with an older (or newer) official release. This greatly reduces the range of commits that potentially need to be built from source and tested. You can find binaries of official releases, as well as alphas, betas, @@ -45,14 +45,14 @@ manage to reproduce the bug with Godot 3.2 beta 1, then try older alpha builds. Instead, use the minor version's first release like Godot 3.1. This is because patch releases are built from a separate *stable branch*. This kind of branch doesn't follow the rest of Godot's development, which is done in - the ``master`` branch. + the `master` branch. The Git bisect command ---------------------- If you've found a build that didn't exhibit the bug in the above testing process, you can now start bisecting the regression. The Git version control -system offers a built-in command for this: ``git bisect``. This makes the +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. @@ -74,7 +74,7 @@ the "bad" and "good" build. "bad" refers to the build that exhibits the bug, whereas "good" refers to the version that doesn't exhibit the bug. If you're using a pre-release build as the "good" or "bad" build, browse the `download mirror `__, go to the folder that -contains the pre-release you downloaded and look for the ``README.txt`` file. +contains the pre-release you downloaded and look for the `README.txt` file. The commit hash is written inside that file. If you're using a stable release as the "good" or "bad" build, use one of the @@ -86,11 +86,11 @@ following commit hashes depending on the version: 3.1-stable 3.0-stable -To refer to the latest state of the master branch, you can use ``master`` +To refer to the latest state of the master branch, you can use `master` instead of a commit hash. `Get Godot's source code using Git `. Once this -is done, in the terminal window, use ``cd`` to reach the Godot repository +is done, in the terminal window, use `cd` to reach the Godot repository folder and enter the following command: .. code-block:: shell @@ -110,10 +110,10 @@ Compile Godot. This assumes you've set up a build environment: $ scons platform= -j4 Since building Godot takes a while, you want to dedicate as many CPU threads as -possible to the task. This is what the ``-j`` parameter does. Here, the command +possible to the task. This is what the `-j` parameter does. Here, the command assigns 4 CPU threads to compiling Godot. -Run the binary located in the ``bin/`` folder and try to reproduce the bug. +Run the binary located in the `bin/` folder and try to reproduce the bug. If the build **still** exhibits the bug, run the following command: @@ -128,8 +128,8 @@ If the build **does not** exhibit the bug, run the following command: $ git bisect good After entering one of the commands above, Git will switch to a different commit. -You should now build Godot again, try to reproduce the bug, then enter ``git -bisect good`` or ``git bisect bad`` depending on the result. You'll have to +You should now build Godot again, try to reproduce the bug, then enter `git +bisect good` or `git bisect bad` depending on the result. You'll have to repeat this several times. The longer the commit range, the more steps will be required. 5 to 10 steps are usually sufficient to find most regressions; Git will remind you of the number of steps remaining (in the worst case scenario). @@ -141,5 +141,5 @@ contributing to Godot :) .. note:: - You can read the full documentation on ``git bisect`` + You can read the full documentation on `git bisect` `here `__. diff --git a/community/contributing/bug_triage_guidelines.rst b/community/contributing/bug_triage_guidelines.rst index 48c0c18..8743ff2 100644 --- a/community/contributing/bug_triage_guidelines.rst +++ b/community/contributing/bug_triage_guidelines.rst @@ -44,7 +44,7 @@ The following labels are currently defined in the Godot repository: compatibility with existing projects. - *Bug*: describes something that is not working properly. - *Cherrypick*: describes something that can be backported to a stable branch - after being merged in the ``master`` branch. + after being merged in the `master` branch. - *Crash:* describes a bug that causes the engine to crash. This label is only used for "hard" crashes, not freezes. - *Confirmed*: has been confirmed by at least one other contributor diff --git a/community/contributing/building_the_manual.rst b/community/contributing/building_the_manual.rst index 81fe4f7..8a9d894 100644 --- a/community/contributing/building_the_manual.rst +++ b/community/contributing/building_the_manual.rst @@ -14,14 +14,14 @@ To get started, you need to: 3. To build the docs as HTML files, install the `readthedocs.org theme `__. 4. Install the Sphinx extensions defined in the `godot-docs repository - `__ ``requirements.txt`` file. + `__ `requirements.txt` file. We recommend using `pip `__, Python’s package manager to install all these tools. It comes pre-installed with `Python `__. 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 `__. .. code:: sh @@ -38,7 +38,7 @@ folder of this repository with the following command: # On Linux and macOS make html - # On Windows, you need to execute the ``make.bat`` file instead. + # On Windows, you need to execute the `make.bat` file instead. make.bat html If you run into errors, you may try the following command: @@ -59,18 +59,18 @@ up compilation by running: # On Windows set SPHINXOPTS=-j2 && make html -The compilation will take some time as the ``classes/`` folder contains hundreds +The compilation will take some time as the `classes/` folder contains hundreds of files. -You can then browse the documentation by opening ``_build/html/index.html`` in +You can then browse the documentation by opening `_build/html/index.html` in your web browser. -In case you of a ``MemoryError`` or ``EOFError``, you can remove the -``classes/`` folder and run ``make`` again. This will drop the class references +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 - working on a pull request or the whole ``classes/`` folder will be +.. 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 `__ for more detail. @@ -101,4 +101,4 @@ root folder: . env/bin/activate pip3 install -r requirements.txt -Then, run ``make html`` as shown above. +Then, run `make html` as shown above. diff --git a/community/contributing/class_reference_writing_guidelines.rst b/community/contributing/class_reference_writing_guidelines.rst index 9de695b..4dfc7b3 100644 --- a/community/contributing/class_reference_writing_guidelines.rst +++ b/community/contributing/class_reference_writing_guidelines.rst @@ -89,20 +89,20 @@ result in a new paragraph, even if it is empty. How to edit class XML --------------------- -Edit the file for your chosen class in ``doc/classes/`` to update the class +Edit the file for your chosen class in `doc/classes/` to update the class 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 - files in the ``modules//doc_classes/`` directory instead. + files in the `modules//doc_classes/` directory instead. Edit it using your favorite text editor. If you use a code editor, make sure that it doesn't change the indent style: you should use tabs for the XML and four spaces inside BBCode-style blocks. More on that below. To check that the modifications you've made are correct in the generated -documentation, navigate to the ``doc/`` folder and run the command ``make rst``. +documentation, navigate to the `doc/` folder and run the command `make rst`. This will convert the XML files to the online documentation's format and output errors if anything's wrong. @@ -143,7 +143,7 @@ the text. Here's the list of available tags: +----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ | [i] [/i] | Italic | Some [i]italic[/i] text. | Some *italic* text. | +----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ -| [code] [/code] | Monospace | Some [code]monospace[/code] text. | Some ``monospace`` text. | +| [code] [/code] | Monospace | Some [code]monospace[/code] text. | Some `monospace` text. | +----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ | [kbd] [/kbd] | Keyboard/mouse shortcut | Some [kbd]Ctrl + C[/kbd] key. | Some :kbd:`Ctrl + C` key. | +----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ @@ -156,7 +156,7 @@ the text. Here's the list of available tags: | [csharp] [/csharp] | C# codeblock tab in codeblocks | *See below.* | *See below.* | +----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ -Use ``[codeblock]`` for pre-formatted code blocks. Inside ``[codeblock]``, +Use `[codeblock]` for pre-formatted code blocks. Inside `[codeblock]`, always use **four spaces** for indentation. The parser will delete tabs. For example: @@ -177,8 +177,8 @@ Will display as: print(sprite.get_pos()) If you need to have different code version in GDScript and C#, use -``[codeblocks]`` instead. If you use ``[codeblocks]``, you also need to have at -least one of the language-specific tags, ``[gdscript]`` and ``[csharp]``. +`[codeblocks]` instead. If you use `[codeblocks]`, you also need to have at +least one of the language-specific tags, `[gdscript]` and `[csharp]`. Always write GDScript code examples first! You can use this `experimental code translation tool `_ to speed up your diff --git a/community/contributing/code_style_guidelines.rst b/community/contributing/code_style_guidelines.rst index ada2774..f83fefb 100644 --- a/community/contributing/code_style_guidelines.rst +++ b/community/contributing/code_style_guidelines.rst @@ -41,11 +41,11 @@ setup clang-format locally to check and automatically fix all your commits. thereof), and don't want to introduce differences that would make syncing with upstream repositories harder. - Third-party code is usually included in the ``thirdparty/`` folder + Third-party code is usually included in the `thirdparty/` folder and can thus easily be excluded from formatting scripts. For the rare cases where a third-party code snippet needs to be included directly within a Godot file, you can use - ``/* clang-format off */`` and ``/* clang-format on */`` to tell + `/* clang-format off */` and `/* clang-format on */` to tell clang-format to ignore a chunk of code. .. seealso:: @@ -73,8 +73,8 @@ Here's how to install clang-format: a Debian derivative, use the `upstream repos `__. - macOS and Windows: You can download precompiled binaries from the `LLVM website `__. You may need to add - the path to the binary's folder to your system's ``PATH`` environment - variable to be able to call ``clang-format`` out of the box. + the path to the binary's folder to your system's `PATH` environment + variable to be able to call `clang-format` out of the box. You then have different possibilities to apply clang-format to your changes: @@ -88,12 +88,12 @@ command: clang-format -i -- ``-i`` means that the changes should be written directly to the file (by +- `-i` means that the changes should be written directly to the file (by default clang-format would only output the fixed version to the terminal). - The path can point to several files, either one after the other or using wildcards like in a typical Unix shell. Be careful when globbing so that you don't run clang-format on compiled objects (.o and .a files) that are - in Godot's tree. So better use ``core/*.{cpp,h}`` than ``core/*``. + in Godot's tree. So better use `core/*.{cpp,h}` than `core/*`. Pre-commit hook ^^^^^^^^^^^^^^^ @@ -102,11 +102,11 @@ For ease of use, we provide a pre-commit hook for Git that will run clang-format automatically on all your commits to check them, and let you apply its changes in the final commit. -This "hook" is a script which can be found in ``misc/hooks``, refer to that +This "hook" is a script which can be found in `misc/hooks`, refer to that folder's README.md for installation instructions. -If your clang-format is not in the ``PATH``, you may have to edit the -``pre-commit-clang-format`` to point to the correct binary for it to work. +If your clang-format is not in the `PATH`, you may have to edit the +`pre-commit-clang-format` to point to the correct binary for it to work. The hook was tested on Linux and macOS, but should also work in the Git Shell on Windows. @@ -122,7 +122,7 @@ Here is a non-exhaustive list of beautifier plugins for some IDEs: - Visual Studio Code: `Clang-Format `__ - Visual Studio: `ClangFormat `__ - vim: `vim-clang-format `__ -- CLion: Starting from version ``2019.1``, no plugin is required. Instead, enable +- CLion: Starting from version `2019.1`, no plugin is required. Instead, enable `ClangFormat `__ (Pull requests welcome to extend this list with tested plugins.) @@ -137,20 +137,20 @@ ones, the following rules should be followed: - The first lines in the file should be Godot's copyright header and MIT license, copy-pasted from another file. Make sure to adjust the filename. -- In a ``.h`` header, include guards should be used with the form - ``FILENAME_H``. +- In a `.h` header, include guards should be used with the form + `FILENAME_H`. -- In a ``.cpp`` file (e.g. ``filename.cpp``), the first include should be the - one where the class is declared (e.g. ``#include "filename.h"``), followed by +- In a `.cpp` file (e.g. `filename.cpp`), the first include should be the + one where the class is declared (e.g. `#include "filename.h"`), followed by an empty line for separation. - Then come headers from Godot's own code base, included in alphabetical order - (enforced by ``clang-format``) with paths relative to the root folder. Those - includes should be done with quotes, e.g. ``#include "core/object.h"``. The + (enforced by `clang-format`) with paths relative to the root folder. Those + includes should be done with quotes, e.g. `#include "core/object.h"`. The block of Godot header includes should then be followed by an empty line for separation. -- Finally, third-party headers (either from ``thirdparty`` or from the system's +- Finally, third-party headers (either from `thirdparty` or from the system's include paths) come next and should be included with the < and > symbols, e.g. - ``#include ``. The block of third-party headers should also be followed + `#include `. The block of third-party headers should also be followed by an empty line for separation. - Godot and third-party headers should be included in the file that requires them, i.e. in the `.h` header if used in the declarative code or in the `.cpp` @@ -246,10 +246,10 @@ Example: Java ---- -Godot's Java code (mostly in ``platform/android``) is also enforced via -``clang-format``, so see the instructions above to set it up. Keep in mind that +Godot's Java code (mostly in `platform/android`) is also enforced via +`clang-format`, so see the instructions above to set it up. Keep in mind that this style guide only applies to code written and maintained by Godot, not -third-party code such as the ``java/src/com/google`` subfolder. +third-party code such as the `java/src/com/google` subfolder. Python ------ @@ -281,14 +281,14 @@ You then have different possibilities to apply black to your changes: Manual usage ^^^^^^^^^^^^ -You can apply ``black`` manually to one or more files with the following +You can apply `black` manually to one or more files with the following command: :: black -l 120 -- ``-l 120`` means that the allowed number of characters per line is 120. +- `-l 120` means that the allowed number of characters per line is 120. This number was agreed upon by the developers. - The path can point to several files, either one after the other or using wildcards like in a typical Unix shell. @@ -300,8 +300,8 @@ For ease of use, we provide a pre-commit hook for Git that will run black automatically on all your commits to check them, and let you apply its changes in the final commit. -This "hook" is a script which can be found in ``misc/hooks``. Refer to that -folder's ``README.md`` for installation instructions. +This "hook" is a script which can be found in `misc/hooks`. Refer to that +folder's `README.md` for installation instructions. Editor integration @@ -322,7 +322,7 @@ Godot's codebase. always end them with a period. - Reference variable/function names and values using backticks. - Wrap comments to ~100 characters. -- You can use ``TODO:``, ``FIXME:``, ``NOTE:``, or ``HACK:`` as adominitions +- You can use `TODO:`, `FIXME:`, `NOTE:`, or `HACK:` as adominitions when needed. **Example:** diff --git a/community/contributing/content_guidelines.rst b/community/contributing/content_guidelines.rst index 2c40103..55c3821 100644 --- a/community/contributing/content_guidelines.rst +++ b/community/contributing/content_guidelines.rst @@ -66,7 +66,7 @@ learn. You can do so by: 1. Introducing only one new concept at a time whenever possible. 2. Using simple English, as we recommend in our writing guidelines. 3. Including one or more **concrete usage examples**. Prefer a real-world example - to abstract code like ``foobar``. + to abstract code like `foobar`. While many people may understand more complex language and abstract examples, you will lose others. Also, understandable writing and practical examples diff --git a/community/contributing/contributing_to_the_documentation.rst b/community/contributing/contributing_to_the_documentation.rst index c7144c4..3c014d8 100644 --- a/community/contributing/contributing_to_the_documentation.rst +++ b/community/contributing/contributing_to_the_documentation.rst @@ -14,7 +14,7 @@ writing or reviewing pages. Getting started --------------- -To modify or create pages in the reference manual, you need to edit ``.rst`` +To modify or create pages in the reference manual, you need to edit `.rst` files in the `godot-docs GitHub repository `_. Modifying those pages in a pull request triggers a rebuild of the online documentation upon merging. @@ -49,8 +49,8 @@ contribute, you should also read: Contributing changes -------------------- -**Pull Requests should use the** ``master`` **branch by default.** Only make Pull -Requests against other branches (e.g. ``2.1`` or ``3.0``) if your changes only +**Pull Requests should use the** `master` **branch by default.** Only make Pull +Requests against other branches (e.g. `2.1` or `3.0`) if your changes only apply to that specific version of Godot. Though less convenient to edit than a wiki, this Git repository is where we @@ -60,9 +60,9 @@ control system is a plus to ensure our documentation quality. Editing existing pages ~~~~~~~~~~~~~~~~~~~~~~ -To edit an existing page, locate its ``.rst`` source file and open it in your +To edit an existing page, locate its `.rst` source file and open it in your favorite text editor. You can then commit the changes, push them to your fork, -and make a pull request. **Note that the pages in** ``classes/`` **should not be +and make a pull request. **Note that the pages in** `classes/` **should not be edited here.** They are automatically generated from Godot’s `XML class reference `__. See `doc_updating_the_class_reference` for details. @@ -109,12 +109,12 @@ Before adding a new page, please ensure that it fits in the documentation: 2. Ensure there isn't a page that already covers the topic. 3. Read our `doc_content_guidelines`. -To add a new page, create a ``.rst`` file with a meaningful name in the section you -want to add a file to, e.g. ``tutorials/3d/light_baking.rst``. +To add a new page, create a `.rst` file with a meaningful name in the section you +want to add a file to, e.g. `tutorials/3d/light_baking.rst`. You should then add your page to the relevant "toctree" (table of contents, -e.g. ``tutorials/3d/index.rst``). Add your new filename to the list on a new -line, using a relative path and no extension, e.g. here ``light_baking``. +e.g. `tutorials/3d/index.rst`). Add your new filename to the list on a new +line, using a relative path and no extension, e.g. here `light_baking`. Titles ~~~~~~ @@ -128,9 +128,9 @@ Always begin pages with their title and a Sphinx reference name: Insert your title here ====================== -The reference ``_doc_insert_your_title_here`` and the title should match. +The reference `_doc_insert_your_title_here` and the title should match. -The reference allows linking to this page using the ```` format, e.g. +The reference allows linking to this page using the ``` format, e.g. ```doc_insert_your_title_here``` would link to the above example page (note the lack of leading underscore in the reference). @@ -150,17 +150,17 @@ and the `official reference `__ for details on the syntax. Sphinx uses specific reST comments to do specific operations, like defining the -table of contents (``.. toctree::``) or cross-referencing pages. Check the +table of contents (`.. toctree::`) or cross-referencing pages. Check the `official Sphinx documentation `__ for more details. To learn -how to use Sphinx directives like ``.. note::`` or ``.. seealso::``, check out +how to use Sphinx directives like `.. note::` or `.. seealso::`, check out the `Sphinx directives documentation `__. Adding images and attachments ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To add images, please put them in an ``img/`` folder next to the ``.rst`` file with +To add images, please put them in an `img/` folder next to the `.rst` file with a meaningful name and include them in your page with: .. code:: rst @@ -168,7 +168,7 @@ a meaningful name and include them in your page with: .. image:: img/image_name.png Similarly, you can include attachments, like assets as support material for a -tutorial, by placing them into a ``files/`` folder next to the ``.rst`` file, and +tutorial, by placing them into a `files/` folder next to the `.rst` file, and using this inline markup: .. code:: rst diff --git a/community/contributing/cpp_usage_guidelines.rst b/community/contributing/cpp_usage_guidelines.rst index d61919e..3d05014 100644 --- a/community/contributing/cpp_usage_guidelines.rst +++ b/community/contributing/cpp_usage_guidelines.rst @@ -40,8 +40,8 @@ modules or GDNative scripts. Disallowed features ------------------- -**Any feature not listed below is allowed.** Using features like ``constexpr`` -variables and ``nullptr`` is encouraged when possible. Still, try to keep your +**Any feature not listed below is allowed.** Using features like `constexpr` +variables and `nullptr` is encouraged when possible. Still, try to keep your use of modern C++ features conservative. Their use needs to serve a real purpose, such as improving code readability or performance. @@ -52,13 +52,13 @@ We don't allow using the `STL `__, available both online and in the editor (ca. 200,000 words). -To manage translations, we use the GNU gettext file format (``PO`` files), and +To manage translations, we use the GNU gettext file format (`PO` files), and the open source `Weblate `__ web-based localization platform, which allows easy collaboration of many contributors to complete the translation for the various components, and keep them up to date. Click the bold @@ -75,9 +75,9 @@ to translate to: .. important:: If your language is spoken in several countries with only limited regional - variations, please consider adding it with its generic variant (e.g. ``fr`` - for French) instead of a regional variant (e.g. ``fr_FR`` for French - (France), ``fr_CA`` for French (Canada), or ``fr_DZ`` for French (Algeria)). + variations, please consider adding it with its generic variant (e.g. `fr` + for French) instead of a regional variant (e.g. `fr_FR` for French + (France), `fr_CA` for French (Canada), or `fr_DZ` for French (Algeria)). Godot has a huge amount of content to translate, so duplicating the work for regional variants should only be done if the language variations are @@ -89,9 +89,9 @@ to translate to: translations, we advise to focus on completing a generic variant first if possible, then duplicate the fully completed translation for regional variants and do the relevant edits. This is typically a good strategy for - e.g. Spanish (work on ``es`` first, then duplicate it to ``es_AR``, - ``es_ES``, ``es_MX``, etc. if necessary) or Portuguese (``pt_BR`` vs - ``pt_PT``). + e.g. Spanish (work on `es` first, then duplicate it to `es_AR`, + `es_ES`, `es_MX`, etc. if necessary) or Portuguese (`pt_BR` vs + `pt_PT`). Translation interface ^^^^^^^^^^^^^^^^^^^^^ @@ -142,8 +142,8 @@ On that page, you have: Locating original content ------------------------- -PO files are an ordered list of source strings (``msgid``) and their translation -(``msgstr``), and by default, Weblate will present the strings in that order. It +PO files are an ordered list of source strings (`msgid`) and their translation +(`msgstr`), and by default, Weblate will present the strings in that order. It can therefore be useful to understand how the content is organized in the PO files to help you locate the original content and use it as a reference when translating. @@ -161,8 +161,8 @@ translating. - The editor interface's translation template is generated by parsing all the C++ source code in **alphabetical order**, so all the strings defined in a given file will be grouped together. For example, if the "source string - location" indicates ``editor/code_editor.cpp``, the current string (and the - nearby ones) is defined in the ``editor/code_editor.cpp`` code file, and is + location" indicates `editor/code_editor.cpp`, the current string (and the + nearby ones) is defined in the `editor/code_editor.cpp` code file, and is thereby related to the code editors in Godot (GDScript, shaders). - The online documentation's translation template is generated from the source RST files in the same order as seen in the **table of contents**, so for @@ -171,7 +171,7 @@ translating. a page that you want to translate, and then translate all the strings with the same source string location while comparing with the online version of that page in English. An example of source string location could be - ``getting_started/step_by_step/nodes_and_scenes.rst`` for the + `getting_started/step_by_step/nodes_and_scenes.rst` for the page `doc_nodes_and_scenes`. - The class reference's translation template is generated from the source XML files in **alphabetical order**, which is also the same as the order of the @@ -180,11 +180,11 @@ translating. first string to translate and all other descriptions from that class should be in the subsequent strings on Weblate. For example, the descriptions for the `Node2D` class would have the source string location - ``doc/classes/Node2D.xml``. + `doc/classes/Node2D.xml`. A handy tool to locate specific pages/classes is to use Weblate's advanced search feature, and especially the "Location strings" query (which can also be -used with the ``location:`` token, e.g. ``location:nodes_and_scenes.rst``): +used with the `location:` token, e.g. `location:nodes_and_scenes.rst`): .. image:: img/l10n_05_search_location.png @@ -194,9 +194,9 @@ used with the ``location:`` token, e.g. ``location:nodes_and_scenes.rst``): When a given source string is used in multiple source locations, they will all be concatenated into one. For example, the above - ``location:nodes_and_scenes.rst`` query would land first on the + `location:nodes_and_scenes.rst` query would land first on the "Introduction" source string which is used in dozens of pages, including - some that come before ``nodes_and_scenes.rst`` in the template. Clicking the + some that come before `nodes_and_scenes.rst` in the template. Clicking the "Next" button then brings us to the "Scene and nodes" title string displayed above. So it may happen that a given paragraph or section title is not at the @@ -214,12 +214,12 @@ Editor interface (C++) The editor translations originate from C++ strings, and may use: -- **C format specifiers** such as ``%s`` (a string) or ``%d`` (a number). These +- **C format specifiers** such as `%s` (a string) or `%d` (a number). These specifiers are replaced by content at runtime, and should be preserved and placed in your translation where necessary for it to be meaningful after substitution. You may need to refer to the source string location to understand what kind of content will be substituted if it's not clear from the - sentence. Example (``%s`` will be substituted with a file name or path):: + sentence. Example (`%s` will be substituted with a file name or path):: # PO file: "There is no '%s' file." @@ -227,9 +227,9 @@ The editor translations originate from C++ strings, and may use: # Weblate: There is no '%s' file. -- **C escape characters** such as ``\n`` (line break) or ``\t`` (tabulation). In - the Weblate editor, the ``\n`` characters are replaced by ``↵`` (return) and - ``\t`` by ``↹``. Tabs are not used much, but you should make sure to use line +- **C escape characters** such as `\n` (line break) or `\t` (tabulation). In + the Weblate editor, the `\n` characters are replaced by `↵` (return) and + `\t` by `↹`. Tabs are not used much, but you should make sure to use line breaks in the same way as the original English string (Weblate will issue a warning if you don't). Line breaks might sometimes be used for vertical spacing, or manual wrapping of long lines which would otherwise be too long @@ -245,7 +245,7 @@ The editor translations originate from C++ strings, and may use: .. note:: Only logical order of the characters matters, in the right-to-left text, format - specifiers may be displayed as ``s%``. + specifiers may be displayed as `s%`. Online documentation (RST) ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -269,7 +269,7 @@ external links, etc. Here are some examples:: # Note: Inline code in RST uses 2 backticks on each side, unlike Markdown. # Single backticks are used for hyperlinks. - |supported| Backwards-compatible new features (backported from the ``master`` + |supported| Backwards-compatible new features (backported from the `master` branch) as well as bug, security, and platform support fixes. # The Sphinx "role" is used for internal references to other pages of @@ -303,11 +303,11 @@ Class reference (BBCode) The class reference is documented in the main Godot repository using XML files, and with BBCode-like markup for styling and internal references. -Some of the tags used are from the original BBCode (e.g. ``[b]Bold[/b]`` and -``[i]Italics[/i]``), while others are Godot-specific and used for advanced -features such as inline code (e.g. ``[code]true[/code]``), linking to another -class (e.g. ``[Node2D]``) or to a property in a given class (e.g. -``[member Node2D.position]``), or for multiline code blocks. Example:: +Some of the tags used are from the original BBCode (e.g. `[b]Bold[/b]` and +`[i]Italics[/i]`), while others are Godot-specific and used for advanced +features such as inline code (e.g. `[code]true[/code]`), linking to another +class (e.g. `[Node2D]`) or to a property in a given class (e.g. +`[member Node2D.position]`), or for multiline code blocks. Example:: Returns a color according to the standardized [code]name[/code] with [code]alpha[/code] ranging from 0 to 1. [codeblock] @@ -315,12 +315,12 @@ class (e.g. ``[Node2D]``) or to a property in a given class (e.g. [/codeblock] Supported color names are the same as the constants defined in [Color]. -In the above example, ``[code]name[/code]``, ``[code]alpha[/code]``, and -``[Color]`` should *not* be translated, as they refer respectively to argument +In the above example, `[code]name[/code]`, `[code]alpha[/code]`, and +`[Color]` should *not* be translated, as they refer respectively to argument names and a class of the Godot API. Similarly, the contents of the -``[codeblock]`` should not be translated, as ``ColorN`` is a function of the -Godot API and ``"red"`` is one of the named colors it supports. At most, you can -translate the name of the variable which holds the result (``red = ...``). +`[codeblock]` should not be translated, as `ColorN` is a function of the +Godot API and `"red"` is one of the named colors it supports. At most, you can +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. @@ -359,12 +359,12 @@ upload mode. If you want to test changes locally (especially for the editor translation), you can use the downloaded PO file and `compile Godot from source `. -Rename the editor translation PO file to ``.po`` (e.g. ``eo.po`` for -Esperanto) and place it in the ``editor/translations/`` folder +Rename the editor translation PO file to `.po` (e.g. `eo.po` for +Esperanto) and place it in the `editor/translations/` folder (`GitHub `__). You can also test class reference changes the same way by renaming the PO file -similarly and placing it in the ``doc/translations/`` folder +similarly and placing it in the `doc/translations/` folder (`GitHub `__). Localizing documentation images @@ -394,23 +394,23 @@ top right corner: On GitHub, click on the image you want to translate. If relevant, click on "Download" to download it locally and edit it with an image edition tool. Note the full path to the image as it will be needed further down (here -``getting_started/step_by_step/img/project_manager_first_open.png``). +`getting_started/step_by_step/img/project_manager_first_open.png`). .. image:: img/l10n_09_path_to_image.png Create your localized version of the image, either by editing the English one, or by taking a screenshot of the editor with your language, if it's an editor screenshot. Some images may also have source files available in SVG format, so -you can browse the ``img/`` folder which contains them to check for that. +you can browse the `img/` folder which contains them to check for that. Name your localized image like the original one, but with the language code -added before the extension, e.g. ``project_manager_first_open.png`` would become -``project_manager_first_open.fr.png`` for the French localization. +added before the extension, e.g. `project_manager_first_open.png` would become +`project_manager_first_open.fr.png` for the French localization. Finally, on godot-docs-l10n_, recreate the same folder structure as for the -original image in the ``images`` subfolder +original image in the `images` subfolder (`GitHub `_), and place your translated image there. In our example, the end result should be -``images/getting_started/step_by_step/img/project_manager_first_open.fr.png``. +`images/getting_started/step_by_step/img/project_manager_first_open.fr.png`. Repeat this for other images and `make a Pull Request `. diff --git a/community/contributing/pr_workflow.rst b/community/contributing/pr_workflow.rst index 77dd883..9ef6426 100644 --- a/community/contributing/pr_workflow.rst +++ b/community/contributing/pr_workflow.rst @@ -51,22 +51,22 @@ which quickly leads to PRs with an unreadable Git history (especially after peer The branches on the Git repository are organized as follows: -- The ``master`` branch is where the development of the next major version +- The `master` branch is where the development of the next major version occurs. As a development branch, it can be unstable and is not meant for use in production. This is where PRs should be done in priority. -- The stable branches are named after their version, e.g. ``3.1`` and ``2.1``. - They are used to backport bugfixes and enhancements from the ``master`` +- The stable branches are named after their version, e.g. `3.1` and `2.1`. + They are used to backport bugfixes and enhancements from the `master` branch to the currently maintained stable release (e.g. 3.1.2 or 2.1.6). As a rule of thumb, the last stable branch is maintained until the next - minor version (e.g. the ``3.0`` branch was maintained until the release of + minor version (e.g. the `3.0` branch was maintained until the release of Godot 3.1). If you want to make PRs against a maintained stable branch, please check - first if your changes are also relevant for the ``master`` branch, and if so - make the PR for the ``master`` branch in priority. Release managers can then + first if your changes are also relevant for the `master` branch, and if so + make the PR for the `master` branch in priority. Release managers can then cherry-pick the fix to a stable branch if relevant. - There might occasionally be feature branches, usually meant to be merged into - the ``master`` branch at some time. + the `master` branch at some time. Forking and cloning ------------------- @@ -101,8 +101,8 @@ To clone your fork from GitHub, use the following command: on typical UNIX shells. It is not part of the command and should not be typed. -After a little while, you should have a ``godot`` directory in your current -working directory. Move into it using the ``cd`` command: +After a little while, you should have a `godot` directory in your current +working directory. Move into it using the `cd` command: :: @@ -115,14 +115,14 @@ We will start by setting up a reference to the original repository that we forke $ git remote add upstream https://github.com/godotengine/godot $ git fetch upstream -This will create a reference named ``upstream`` pointing to the original -``godotengine/godot`` repository. This will be useful when you want to pull new -commits from its ``master`` branch to update your fork. You have another -remote reference named ``origin``, which points to your fork (``USERNAME/godot``). +This will create a reference named `upstream` pointing to the original +`godotengine/godot` repository. This will be useful when you want to pull new +commits from its `master` branch to update your fork. You have another +remote reference named `origin`, which points to your fork (`USERNAME/godot`). 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). +`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 it... technologic.* @@ -136,14 +136,14 @@ metadata is hidden in its ``.git`` subfolder). working in Git. In the following, we will assume as an example that you want to implement a feature in -Godot's project manager, which is coded in the ``editor/project_manager.cpp`` +Godot's project manager, which is coded in the `editor/project_manager.cpp` file. Branching --------- -By default, the ``git clone`` should have put you on the ``master`` branch of -your fork (``origin``). To start your own feature development, we will create +By default, the `git clone` should have put you on the `master` branch of +your fork (`origin`). To start your own feature development, we will create a feature branch: :: @@ -161,13 +161,13 @@ This command is equivalent: # Change the current branch to a new named one, based on the current branch $ git checkout -b better-project-manager -If you want to go back to the ``master`` branch, you'd use: +If you want to go back to the `master` branch, you'd use: :: $ git checkout master -You can see which branch you are currently on with the ``git branch`` +You can see which branch you are currently on with the `git branch` command: :: @@ -177,7 +177,7 @@ command: * better-project-manager master -Be sure to always go back to the ``master`` branch before creating a new branch, +Be sure to always go back to the `master` branch before creating a new branch, as your current branch will be used as the base for the new one. Alternatively, you can specify a custom base branch after the new branch's name: @@ -190,40 +190,40 @@ Updating your branch This would not be needed the first time (just after you forked the upstream repository). However, the next time you want to work on something, you will -notice that your fork's ``master`` is several commits behind the upstream -``master`` branch: pull requests from other contributors would have been merged +notice that your fork's `master` is several commits behind the upstream +`master` branch: pull requests from other contributors would have been merged in the meantime. To ensure there won't be conflicts between the feature you develop and the -current upstream ``master`` branch, you will have to update your branch by +current upstream `master` branch, you will have to update your branch by *pulling* the upstream branch. :: $ git pull --rebase upstream master -The ``--rebase`` argument will ensure that any local changes that you committed +The `--rebase` argument will ensure that any local changes that you committed will be re-applied *on top* of the pulled branch, which is usually what we want in our PR workflow. This way, when you open a pull request, your own commits will -be the only difference with the upstream ``master`` branch. +be the only difference with the upstream `master` branch. While rebasing, conflicts may arise if your commits modified code that has been changed in the upstream branch in the meantime. If that happens, Git will stop at the conflicting commit and will ask you to resolve the conflicts. You can do so with any text editor, then stage the changes (more on that later), and proceed with -``git rebase --continue``. Repeat the operation if later commits have conflicts too, +`git rebase --continue`. Repeat the operation if later commits have conflicts too, until the rebase operation completes. If you're unsure about what is going on during a rebase and you panic (no worry, -we all do the first few times), you can abort the rebase with ``git rebase --abort``. +we all do the first few times), you can abort the rebase with `git rebase --abort`. You will then be back to the original state of your branch before calling -``git pull --rebase``. +`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. - While this is a valid workflow and the default behavior of ``git pull``, + While this is a valid workflow and the default behavior of `git pull`, merge commits within PRs are frowned upon in our PR workflow. We only use them when merging PRs into the upstream branch. @@ -234,58 +234,58 @@ You will then be back to the original state of your branch before calling things right the first time, and we're happy to use it to ensure that changes are easy to review and understand long after they have been merged. -If you have already created a merge commit without using ``rebase``, or +If you have already created a merge commit without using `rebase`, or have made any other changes that have resulted in undesired history, the best option is to use an *interactive rebase* on the upstream branch. See the `dedicated section ` for instructions. .. tip:: If at any time you want to *reset* a local branch to a given commit or branch, - you can do so with ``git reset --hard `` or - ``git reset --hard /`` (e.g. ``git reset --hard upstream/master``). + you can do so with `git reset --hard ` or + `git reset --hard /` (e.g. `git reset --hard upstream/master`). Be warned that this will remove any changes that you might have committed in - this branch. If you ever lose commits by mistake, use the ``git reflog`` command + this branch. If you ever lose commits by mistake, use the `git reflog` command to find the commit ID of the previous state that you would like to restore, and - use it as argument of ``git reset --hard`` to go back to that state. + use it as argument of `git reset --hard` to go back to that state. Making changes -------------- You would then do your changes to our example's -``editor/project_manager.cpp`` file with your usual development environment +`editor/project_manager.cpp` file with your usual development environment (text editor, IDE, etc.). By default, those changes are *unstaged*. The staging area is a layer between your working directory (where you make your modifications) and the local Git -repository (the commits and all the metadata in the ``.git`` folder). To +repository (the commits and all the metadata in the `.git` folder). To bring changes from the working directory to the Git repository, you need to -*stage* them with the ``git add`` command, and then to commit them with the -``git commit`` command. +*stage* them with the `git add` command, and then to commit them with the +`git commit` command. There are various commands you should know to review your current work, before staging it, while it is staged, and after it has been committed. -- ``git diff`` will show you the current unstaged changes, i.e. the +- `git diff` will show you the current unstaged changes, i.e. the differences between your working directory and the staging area. -- ``git checkout -- `` will undo the unstaged changes to the given +- `git checkout -- ` will undo the unstaged changes to the given files. -- ``git add `` will *stage* the changes on the listed files. -- ``git diff --staged`` will show the current staged changes, i.e. the +- `git add ` will *stage* the changes on the listed files. +- `git diff --staged` will show the current staged changes, i.e. the differences between the staging area and the last commit. -- ``git reset HEAD `` will *unstage* changes to the listed files. -- ``git status`` will show you what are the currently staged and unstaged +- `git reset HEAD ` will *unstage* changes to the listed files. +- `git status` will show you what are the currently staged and unstaged modifications. -- ``git commit`` will commit the staged files. It will open a text editor - (you can define the one you want to use with the ``GIT_EDITOR`` environment - variable or the ``core.editor`` setting in your Git configuration) to let you - write a commit log. You can use ``git commit -m "Cool commit log"`` to +- `git commit` will commit the staged files. It will open a text editor + (you can define the one you want to use with the `GIT_EDITOR` environment + variable or the `core.editor` setting in your Git configuration) to let you + write a commit log. You can use `git commit -m "Cool commit log"` to write the log directly. -- ``git commit --amend`` lets you amend the last commit with your currently - staged changes (added with ``git add``). This is the best option if you +- `git commit --amend` lets you amend the last commit with your currently + staged changes (added with `git add`). This is the best option if you want to fix a mistake in the last commit (bug, typo, style issue, etc.). -- ``git log`` will show you the last commits of your current branch. If you +- `git log` will show you the last commits of your current branch. If you did local commits, they should be shown at the top. -- ``git show`` will show you the changes of the last commit. You can also +- `git show` will show you the changes of the last commit. You can also specify a commit hash to see the changes for that commit. That's a lot to memorize! Don't worry, just check this cheat sheet when you @@ -323,14 +323,14 @@ Here's how the shell history could look like on our example: $ git commit -m "Add a pretty banner to the project manager" $ git log -With this, we should have two new commits in our ``better-project-manager`` -branch which were not in the ``master`` branch. They are still only local +With this, we should have two new commits in our `better-project-manager` +branch which were not in the `master` branch. They are still only local though, the remote fork does not know about them, nor does the upstream repo. Pushing changes to a remote --------------------------- -That's where ``git push`` will come into play. In Git, a commit is always +That's where `git push` will come into play. In Git, a commit is always done in the local repository (unlike Subversion where a commit will modify the remote repository directly). You need to *push* the new commits to a remote branch to share them with the world. The syntax for this is: @@ -356,13 +356,13 @@ Issuing a pull request When you load your fork's branch on GitHub, you should see a line saying *"This branch is 2 commits ahead of godotengine:master."* (and potentially some -commits behind, if your ``master`` branch was out of sync with the upstream -``master`` branch). +commits behind, if your `master` branch was out of sync with the upstream +`master` branch). .. image:: img/github_fork_make_pr.png On that line, there is a "Pull request" link. Clicking it will open a form -that will let you issue a pull request on the ``godotengine/godot`` upstream +that will let you issue a pull request on the `godotengine/godot` upstream repository. It should show you your two commits, and state "Able to merge". If not (e.g. it has way more commits, or says there are merge conflicts), don't create the PR yet, something went wrong. Go to our @@ -400,7 +400,7 @@ codebase from one functional state to another functional state, without having intermediate commits fixing up bugs in your own code or style issues. Most of the time, we will prefer a single commit in a given PR (unless there's a good reason to keep the changes separate). Instead of authoring a new commit, -consider using ``git commit --amend`` to amend the previous commit with your +consider using `git commit --amend` to amend the previous commit with your fixes. The above example would then become: :: @@ -442,35 +442,35 @@ history*. Right, we have that power. You may read that it's a bad practice, and it's true when it comes to branches of the upstream repo. But in your fork, you can do whatever you want, and everything is allowed to get neat PRs :) -We will use the *interactive rebase* ``git rebase -i`` to do this. This +We will use the *interactive rebase* `git rebase -i` to do this. This command takes a commit ID or a branch name as argument, and will let you modify all commits between that commit/branch and the last one in your working branch, -the so-called ``HEAD``. +the so-called `HEAD`. -While you can give any commit ID to ``git rebase -i`` and review everything in +While you can give any commit ID to `git rebase -i` and review everything in between, the most common and convenient workflow involves rebasing on the -upstream ``master`` branch, which you can do with: +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 - 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. + 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. Interactive rebases can only be done on local branches, so the `/` is important here. As the upstream remote changes frequently, your - local ``upstream/master`` branch may become outdated, so you can - update it with ``git fetch upstream master``. Contrarily to - ``git pull --rebase upstream master`` which would update your - currently checked out branch, ``fetch`` will only update the - ``upstream/master`` reference (which is distinct from your local - ``master`` branch... yes it's confusing, but you'll become familiar + local `upstream/master` branch may become outdated, so you can + update it with `git fetch upstream master`. Contrarily to + `git pull --rebase upstream master` which would update your + currently checked out branch, `fetch` will only update the + `upstream/master` reference (which is distinct from your local + `master` branch... yes it's confusing, but you'll become familiar with this little by little). -This will open a text editor (``vi`` by default, see +This will open a text editor (`vi` by default, see `Git docs `_ to configure your favorite one) with something which may look like this: @@ -493,7 +493,7 @@ so we use: fixup e07077e Fix a typo in the banner's title Upon saving and quitting the editor, the rebase will occur. The second commit -will be melded into the first one, and ``git log`` and ``git show`` should +will be melded into the first one, and `git log` and `git show` should now confirm that you have only one commit with the changes from both previous commits. @@ -520,7 +520,7 @@ will have to *force* it: $ git push --force origin better-project-manager And tadaa! Git will happily *replace* your remote branch with what you had -locally (so make sure that's what you wanted, using ``git log``). This will +locally (so make sure that's what you wanted, using `git log`). This will also update the PR accordingly. Deleting a Git branch @@ -538,7 +538,7 @@ To delete our better project manager branch locally, use this command: $ git branch -d better-project-manager Alternatively, if the branch hadn't been merged yet and we wanted to delete it anyway, instead -of ``-d`` you would use ``-D``. +of `-d` you would use `-D`. Next, to delete the remote branch on GitHub use this command: diff --git a/community/contributing/testing_pull_requests.rst b/community/contributing/testing_pull_requests.rst index a01a886..d0a1e98 100644 --- a/community/contributing/testing_pull_requests.rst +++ b/community/contributing/testing_pull_requests.rst @@ -61,8 +61,8 @@ to generate a universal download link. .. image:: img/testing_pull_requests_access_fork.png -- Now that you are on the fork's branch page, click the ``.github`` folder at the top of the file list. - Then, click on the ``workflows`` folder (whicb is inside the ``.github`` folder). +- Now that you are on the fork's branch page, click the `.github` folder at the top of the file list. + Then, click on the `workflows` folder (whicb is inside the `.github` folder). Click the workflow file for the platform you wish to download artifacts for. *After* clicking on the file (which opens the file view), copy the page URL from your browser's address bar. diff --git a/community/contributing/updating_the_class_reference.rst b/community/contributing/updating_the_class_reference.rst index 6c72f9c..c5d49a3 100644 --- a/community/contributing/updating_the_class_reference.rst +++ b/community/contributing/updating_the_class_reference.rst @@ -41,10 +41,10 @@ repository: `doc/classes/ `_. .. note:: For some modules in the engine's source code, you'll find the XML - files in the ``modules//doc_classes/`` directory instead. + files in the `modules//doc_classes/` directory instead. .. warning:: Always edit the API reference through these source XML files. Do - not edit the generated ``.rst`` files `in the online documentation + not edit the generated `.rst` files `in the online documentation `, hosted in the `godot-docs `_ repository. @@ -61,16 +61,16 @@ repository: `doc/classes/ Updating the documentation template ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When you create a new class or modify the engine's API, you need to re-generate the XML files in ``doc/classes/``. +When you create a new class or modify the engine's API, you need to re-generate the XML files in `doc/classes/`. To do so, you first need to compile Godot. See the `doc_introduction_to_the_buildsystem` page to learn how. Then, execute the -compiled Godot binary from the Godot root directory with the ``--doctool`` option. +compiled Godot binary from the Godot root directory with the `--doctool` option. For example, if you're on 64-bit Linux, the command is:: ./bin/godot.linuxbsd.tools.64 --doctool The XML files in doc/classes should then be up-to-date with current Godot Engine -features. You can then check what changed using the ``git diff`` command. Please +features. You can then check what changed using the `git diff` command. Please only include changes that are relevant to your work on the API in your commits. -You can discard changes in other XML files using ``git checkout``. +You can discard changes in other XML files using `git checkout`. diff --git a/community/contributing/ways_to_contribute.rst b/community/contributing/ways_to_contribute.rst index 7263340..2feb6ce 100644 --- a/community/contributing/ways_to_contribute.rst +++ b/community/contributing/ways_to_contribute.rst @@ -91,7 +91,7 @@ on GitHub. .. seealso:: 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`` + Details about the code style guidelines and the `clang-format` tool used to enforce them are outlined in `doc_code_style_guidelines`. diff --git a/development/compiling/compiling_for_android.rst b/development/compiling/compiling_for_android.rst index d900b22..1b5fb6c 100644 --- a/development/compiling/compiling_for_android.rst +++ b/development/compiling/compiling_for_android.rst @@ -51,20 +51,20 @@ For compiling under Windows, Linux or macOS, the following is required: Setting up the buildsystem -------------------------- -- Set the environment variable ``ANDROID_SDK_ROOT`` to point to the Android +- Set the environment variable `ANDROID_SDK_ROOT` to point to the Android SDK. If you downloaded the Android command-line tools, this would be the folder where you extracted the contents of the ZIP archive. - Install the necessary SDK components in this folder: - Accept the SDK component licenses by running the following command - where ``android_sdk_path`` is the path to the Android SDK, then answering all the prompts with ``y``: + where `android_sdk_path` is the path to the Android SDK, then answering all the prompts with `y`: :: tools/bin/sdkmanager --sdk_root= --licenses - - Complete setup by running the following command where ``android_sdk_path`` is the path to the Android SDK. + - Complete setup by running the following command where `android_sdk_path` is the path to the Android SDK. :: @@ -75,14 +75,14 @@ Setting up the buildsystem pane, then click on **Environment variables** on the window that appears. .. seealso:: 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 + `export ANDROID_SDK_ROOT=/path/to/android-sdk` where `/path/to/android-sdk` points to the root of the SDK directories. Building the export templates ----------------------------- Godot needs two export templates for Android: the optimized "release" -template (``android_release.apk``) and the debug template (``android_debug.apk``). +template (`android_release.apk`) and the debug template (`android_debug.apk`). As Google will require all APKs to include ARMv8 (64-bit) libraries starting from August 2019, the commands below will build an APK containing both ARMv7 and ARMv8 libraries. @@ -103,7 +103,7 @@ root directory with the following arguments: ./gradlew generateGodotTemplates -The resulting APK will be located at ``bin/android_release.apk``. +The resulting APK will be located at `bin/android_release.apk`. - Debug template (used when exporting with **Debugging Enabled** checked) @@ -118,14 +118,14 @@ The resulting APK will be located at ``bin/android_release.apk``. ./gradlew generateGodotTemplates -The resulting APK will be located at ``bin/android_debug.apk``. +The resulting APK will be located at `bin/android_debug.apk`. Adding support for x86 devices ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you also want to include support for x86 and x86-64 devices, run the SCons -command a third and fourth time with the ``android_arch=x86``, and -``android_arch=x86_64`` arguments before building the APK with Gradle. For +command a third and fourth time with the `android_arch=x86`, and +`android_arch=x86_64` arguments before building the APK with Gradle. For example, for the release template: :: @@ -174,17 +174,17 @@ adds your files. Installing the templates ~~~~~~~~~~~~~~~~~~~~~~~~ -The newly-compiled templates (``android_debug.apk`` -and ``android_release.apk``) must be copied to Godot's templates folder +The newly-compiled templates (`android_debug.apk` +and `android_release.apk`) must be copied to Godot's templates folder with their respective names. The templates folder can be located in: -- Windows: ``%APPDATA%\Godot\templates\\`` -- Linux: ``$HOME/.local/share/godot/templates//`` -- macOS: ``$HOME/Library/Application Support/Godot/templates//`` +- Windows: `%APPDATA%\Godot\templates\\` +- Linux: `$HOME/.local/share/godot/templates//` +- macOS: `$HOME/Library/Application Support/Godot/templates//` -```` is of the form ``major.minor[.patch].status`` using values from -``version.py`` in your Godot source repository (e.g. ``3.0.5.stable`` or ``3.1.dev``). -You also need to write this same version string to a ``version.txt`` file located +`` is of the form `major.minor[.patch].status` using values from +`version.py` in your Godot source repository (e.g. `3.0.5.stable` or `3.1.dev`). +You also need to write this same version string to a `version.txt` file located next to your export templates. .. TODO: Move these paths to a common reference page @@ -196,7 +196,7 @@ here: .. image:: img/andtemplates.png You don't even need to copy them, you can just reference the resulting -file in the ``bin\`` directory of your Godot source folder, so that the +file in the `bin\` directory of your Godot source folder, so that the next time you build you will automatically have the custom templates referenced. @@ -206,7 +206,7 @@ Troubleshooting Platform doesn't appear in SCons ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Double-check that you've set the ``ANDROID_SDK_ROOT`` +Double-check that you've set the `ANDROID_SDK_ROOT` environment variable. This is required for the platform to appear in SCons' list of detected platforms. See `Setting up the buildsystem ` @@ -239,10 +239,10 @@ one of the following reasons: - Make sure to use export templates that match your editor version; if you use a new Godot version, you *have* to update the templates too. -- ``libgodot_android.so`` is not in ``libs//`` - where ```` is the device's architecture. +- `libgodot_android.so` is not in `libs//` + where `` is the device's architecture. - The device's architecture does not match the exported one(s). Make sure your templates were built for that device's architecture, and that the export settings included support for that architecture. -In any case, ``adb logcat`` should also show the cause of the error. +In any case, `adb logcat` should also show the cause of the error. diff --git a/development/compiling/compiling_for_ios.rst b/development/compiling/compiling_for_ios.rst index f8edb92..fbae2c8 100644 --- a/development/compiling/compiling_for_ios.rst +++ b/development/compiling/compiling_for_ios.rst @@ -15,7 +15,7 @@ Requirements - SCons 3.0+ (you can install it via `Homebrew `_ or `MacPorts `_, you should be able - to run ``scons`` in a terminal when installed). + 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 @@ -39,7 +39,7 @@ for a debug build, or: $ scons p=iphone target=release -for a release build (check ``platform/iphone/detect.py`` for the compiler +for a release build (check `platform/iphone/detect.py` for the compiler flags used for each configuration). Alternatively, you can run @@ -53,7 +53,7 @@ for a Simulator executable. For recent devices, Apple requires 64-bit versions of application binaries when you are uploading to the Apple Store. The best way to provide these is to create a bundle in which there are both 32-bit and 64-bit binaries, so every device will be able to run the game. -It can be done in three steps: first compile the 32-bit version, then compile the 64-bit version and then use ``lipo`` to bundle them into one "universal" binary. +It can be done in three steps: first compile the 32-bit version, then compile the 64-bit version and then use `lipo` to bundle them into one "universal" binary. All those steps can be performed with following commands: :: @@ -64,7 +64,7 @@ All those steps can be performed with following commands: $ lipo -create bin/libgodot_camera_module.iphone.opt.arm.a bin/libgodot_camera_module.iphone.opt.arm64.a -output bin/libgodot_camera_module.iphone.release.fat.a $ lipo -create bin/libgodot_arkit_module.iphone.opt.arm.a bin/libgodot_arkit_module.iphone.opt.arm64.a -output bin/libgodot_arkit_module.iphone.release.fat.a -If you also want to provide a simulator build (reduces the chance of any linker errors with dependencies), you'll need to build and lipo the ``x86_64`` architecture as well. +If you also want to provide a simulator build (reduces the chance of any linker errors with dependencies), you'll need to build and lipo the `x86_64` architecture as well. :: diff --git a/development/compiling/compiling_for_osx.rst b/development/compiling/compiling_for_osx.rst index fb0bb31..56b6743 100644 --- a/development/compiling/compiling_for_osx.rst +++ b/development/compiling/compiling_for_osx.rst @@ -54,23 +54,23 @@ To compile for Apple Silicon (ARM64) powered Macs, use:: scons platform=osx arch=arm64 --jobs=$(sysctl -n hw.logicalcpu) -To support both architectures in a single "Universal 2" binary, run the above two commands and then use ``lipo`` to bundle them together:: +To support both architectures in a single "Universal 2" binary, run the above two commands and then use `lipo` to bundle them together:: lipo -create bin/godot.osx.tools.x86_64 bin/godot.osx.tools.arm64 -output bin/godot.osx.tools.universal If all goes well, the resulting binary executable will be placed in the -``bin/`` subdirectory. This executable file contains the whole engine and +`bin/` subdirectory. This executable file contains the whole engine and 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 and official releases, you can enable `doc_data_paths_self_contained_mode` by creating a file called - ``._sc_`` or ``_sc_`` in the ``bin/`` folder. + `._sc_` or `_sc_` in the `bin/` folder. -To create an ``.app`` bundle like in the official builds, you need to use the -template located in ``misc/dist/osx_tools.app``. Typically, for an optimized -editor binary built with ``target=release_debug``:: +To create an `.app` bundle like in the official builds, you need to use the +template located in `misc/dist/osx_tools.app`. Typically, for an optimized +editor binary built with `target=release_debug`:: cp -r misc/dist/osx_tools.app ./Godot.app mkdir -p Godot.app/Contents/MacOS @@ -98,13 +98,13 @@ use:: Building export templates ------------------------- -To build macOS export templates, you have to compile with ``tools=no`` (no -editor) and respectively for ``target=release`` (release template) and -``target=release_debug``. +To build macOS export templates, you have to compile with `tools=no` (no +editor) and respectively for `target=release` (release template) and +`target=release_debug`. Official templates are universal binaries which support both Intel x86_64 and ARM64 architectures. You can also create export templates that support only one -of those two architectures by leaving out the ``lipo`` step below. +of those two architectures by leaving out the `lipo` step below. - For Intel x86_64:: @@ -117,17 +117,17 @@ of those two architectures by leaving out the ``lipo`` step below. scons platform=osx tools=no target=release_debug arch=arm64 --jobs=$(sysctl -n hw.logicalcpu) To support both architectures in a single "Universal 2" binary, run the above -two commands blocks and then use ``lipo`` to bundle them together:: +two commands blocks and then use `lipo` to bundle them together:: lipo -create bin/godot.osx.opt.x86_64 bin/godot.osx.opt.arm64 -output bin/godot.osx.opt.universal lipo -create bin/godot.osx.opt.debug.x86_64 bin/godot.osx.opt.debug.arm64 -output bin/godot.osx.opt.debug.universal -To create an ``.app`` bundle like in the official builds, you need to use the -template located in ``misc/dist/osx_template.app``. The release and debug -builds should be placed in ``osx_template.app/Contents/MacOS`` with the names -``godot_osx_release.64`` and ``godot_osx_debug.64`` respectively. You can do so +To create an `.app` bundle like in the official builds, you need to use the +template located in `misc/dist/osx_template.app`. The release and debug +builds should be placed in `osx_template.app/Contents/MacOS` with the names +`godot_osx_release.64` and `godot_osx_debug.64` respectively. You can do so with the following commands (assuming a universal build, otherwise replace the -``.universal`` extension with the one of your arch-specific binaries):: +`.universal` extension with the one of your arch-specific binaries):: cp -r misc/dist/osx_template.app . mkdir -p osx_template.app/Contents/MacOS @@ -135,7 +135,7 @@ with the following commands (assuming a universal build, otherwise replace the cp bin/godot.osx.opt.debug.universal osx_template.app/Contents/MacOS/godot_osx_debug.64 chmod +x osx_template.app/Contents/MacOS/godot_osx* -You can then zip the ``osx_template.app`` folder to reproduce the ``osx.zip`` +You can then zip the `osx_template.app` folder to reproduce the `osx.zip` template from the official Godot distribution:: zip -q -9 -r osx.zip osx_template.app @@ -159,7 +159,7 @@ e.g.:: 2. Follow the instructions to install OSXCross: https://github.com/tpoechtrager/osxcross#installation -After that, you will need to define the ``OSXCROSS_ROOT`` as the path to +After that, you will need to define the `OSXCROSS_ROOT` as the path to the OSXCross installation (the same place where you cloned the repository/extracted the zip), e.g.:: @@ -169,6 +169,6 @@ Now you can compile with SCons like you normally would:: scons platform=osx -If you have an OSXCross SDK version different from the one expected by the SCons buildsystem, you can specify a custom one with the ``osxcross_sdk`` argument:: +If you have an OSXCross SDK version different from the one expected by the SCons buildsystem, you can specify a custom one with the `osxcross_sdk` argument:: scons platform=osx osxcross_sdk=darwin15 diff --git a/development/compiling/compiling_for_uwp.rst b/development/compiling/compiling_for_uwp.rst index ec651e4..b1e9938 100644 --- a/development/compiling/compiling_for_uwp.rst +++ b/development/compiling/compiling_for_uwp.rst @@ -18,11 +18,11 @@ Requirements caveats of installing it and the various prompts. - Windows 10 SDK (can be selected in Visual Studio installation). - `ANGLE source `__. Use the - ``ms_master`` (default) branch. Keep it in a path without spaces to + `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 - ``ms_master`` branch has been cleared out. + `ms_master` branch has been cleared out. As a temporary workaround however, it is still possible to download an older state of the source code via commit @@ -45,10 +45,10 @@ you want to build. Check `doc_compiling_for_windows` to see how these prompts work. There are three target architectures for UWP: x86 (32-bits), x64 (64-bits) -and ARM (32-bits). For the latter, you can run ``vcvarsall.bat`` with -``x86_arm`` or ``amd64_arm`` as argument to set the environment. +and ARM (32-bits). For the latter, you can run `vcvarsall.bat` with +`x86_arm` or `amd64_arm` as argument to set the environment. -Set the ``ANGLE_SRC_PATH`` to the directory where you downloaded the ANGLE +Set the `ANGLE_SRC_PATH` to the directory where you downloaded the ANGLE source code. The build process will also build ANGLE to produce the required DLLs for the selected architecture. @@ -60,7 +60,7 @@ Creating UWP export templates ----------------------------- To export using the editor you need to properly build package the templates. -You need all three architectures with ``debug`` and ``release`` templates to +You need all three architectures with `debug` and `release` templates to be able to export. Open the command prompt for one architecture and run SCons twice (once for @@ -71,17 +71,17 @@ each target):: Repeat for the other architectures. -In the end your ``bin`` folder will have the ``.exe`` binaries with a name -like ``godot.uwp.opt.debug.32.x86.exe`` (with variations for each +In the end your `bin` folder will have the `.exe` binaries with a name +like `godot.uwp.opt.debug.32.x86.exe` (with variations for each target/arch). -Copy one of these to ``misc/dist/uwp_template`` inside the Godot source -folder and rename the binary to ``godot.uwp.exe``. From the ANGLE source, -under ``winrt/10/src/Release_%arch%`` (where ``%arch%`` can be ``Win32``, -``x64`` or ``ARM``), get the ``libEGL.dll`` and the ``libGLESv2.dll``, +Copy one of these to `misc/dist/uwp_template` inside the Godot source +folder and rename the binary to `godot.uwp.exe`. From the ANGLE source, +under `winrt/10/src/Release_%arch%` (where `%arch%` can be `Win32`, +`x64` or `ARM`), get the `libEGL.dll` and the `libGLESv2.dll`, putting them along with the executable. -Add the files in the ``uwp_template`` folder to a ZIP. Rename the resulting +Add the files in the `uwp_template` folder to a ZIP. Rename the resulting Zip according to the target/architecture of the template:: uwp_x86_debug.zip @@ -91,7 +91,7 @@ Zip according to the target/architecture of the template:: uwp_arm_debug.zip uwp_arm_release.zip -Move those templates to the ``[versionstring]\templates`` folder in Godot +Move those templates to the `[versionstring]\templates` folder in Godot settings path, where `versionstring` is the version of Godot you have compiled the export templates for - e.g. `3.0.alpha` for the alpha version of Godot 3. If you don't want to replace the templates, you can set the "Custom Package" @@ -105,40 +105,40 @@ and signing, you can deploy and launch them using Visual Studio. It might be the easiest way if you are testing on a device such as a Windows Phone or an Xbox One. -Within the ANGLE source folder, open ``templates`` and double-click the -``install.bat`` script file. This will install the Visual Studio project +Within the ANGLE source folder, open `templates` and double-click the +`install.bat` script file. This will install the Visual Studio project templates for ANGLE apps. -If you have not built Godot yet, open the ``winrt/10/src/angle.sln`` solution +If you have not built Godot yet, open the `winrt/10/src/angle.sln` solution from the ANGLE source and build it to Release/Win32 target. You may also need to build it for ARM if you plan to run on a device. You can also use MSBuild if you're comfortable with the command line. Create a new Windows App project using the "App for OpenGL ES (Windows Universal)" project template, which can be found under the -``Visual C++/Windows/Universal`` category. +`Visual C++/Windows/Universal` category. This is a base project with the ANGLE dependencies already set up. However, by default it picks the debug version of the DLLs which usually have poor performance. So in the "Binaries" filter, click in each of the DLLs there and in the "Properties" window and change the relative path from -``Debug_Win32`` to ``Release_Win32`` (or ``Release_ARM`` for devices). +`Debug_Win32` to `Release_Win32` (or `Release_ARM` for devices). In the same "Binaries" filter, select "Add > Existing Item" and point to the Godot executable for UWP you have. In the "Properties" window, set "Content" -to ``True`` so it's included in the project. +to `True` so it's included in the project. -Right-click the ``Package.appxmanifest`` file and select "Open With... > XML -(Text) Editor". In the ``Package/Applications/Application`` element, replace -the ``Executable`` attribute from ``$targetnametoken$.exe`` to -``godot.uwp.exe`` (or whatever your Godot executable is called). Also change -the ``EntryPoint`` attribute to ``GodotUWP.App``. This will ensure that +Right-click the `Package.appxmanifest` file and select "Open With... > XML +(Text) Editor". In the `Package/Applications/Application` element, replace +the `Executable` attribute from `$targetnametoken$.exe` to +`godot.uwp.exe` (or whatever your Godot executable is called). Also change +the `EntryPoint` attribute to `GodotUWP.App`. This will ensure that the Godot executable is correctly called when the app starts. -Create a folder (*not* a filter) called ``game`` in your Visual Studio project -folder and there you can put either a ``data.pck`` file or your Godot project +Create a folder (*not* a filter) called `game` in your Visual Studio project +folder and there you can put either a `data.pck` file or your Godot project files. After that, make sure to include it all with the "Add > Existing Item" -command and set their "Content" property to ``True`` so they're copied to the +command and set their "Content" property to `True` so they're copied to the app. To ease the workflow, you can open the "Solution Properties" and in the diff --git a/development/compiling/compiling_for_web.rst b/development/compiling/compiling_for_web.rst index 66304cc..064dd42 100644 --- a/development/compiling/compiling_for_web.rst +++ b/development/compiling/compiling_for_web.rst @@ -28,36 +28,36 @@ To compile export templates for the Web, the following is required: Building export templates ------------------------- -Before starting, confirm that ``emcc`` is available in your PATH. This is -usually configured by the Emscripten SDK, e.g. when invoking ``emsdk activate`` -and ``source ./emsdk_env.sh``/``emsdk_env.bat``. +Before starting, confirm that `emcc` is available in your PATH. This is +usually configured by the Emscripten SDK, e.g. when invoking `emsdk activate` +and `source ./emsdk_env.sh`/`emsdk_env.bat`. Open a terminal and navigate to the root directory of the engine source code. -Then instruct SCons to build the JavaScript platform. Specify ``target`` as -either ``release`` for a release build or ``release_debug`` for a debug build:: +Then instruct SCons to build the JavaScript platform. Specify `target` as +either `release` for a release build or `release_debug` for a debug build:: scons platform=javascript tools=no target=release scons platform=javascript tools=no target=release_debug By default, the `JavaScript singleton ` will be built into the engine. Official export templates also have the JavaScript singleton -enabled. Since ``eval()`` calls can be a security concern, the -``javascript_eval`` option can be used to build without the singleton:: +enabled. Since `eval()` calls can be a security concern, the +`javascript_eval` option can be used to build without the singleton:: scons platform=javascript tools=no target=release javascript_eval=no scons platform=javascript tools=no target=release_debug javascript_eval=no The engine will now be compiled to WebAssembly by Emscripten. Once finished, -the resulting file will be placed in the ``bin`` subdirectory. Its name is -``godot.javascript.opt.zip`` for release or ``godot.javascript.opt.debug.zip`` +the resulting file will be placed in the `bin` subdirectory. Its name is +`godot.javascript.opt.zip` for release or `godot.javascript.opt.debug.zip` for debug. -Finally, rename the zip archive to ``webassembly_release.zip`` for the +Finally, rename the zip archive to `webassembly_release.zip` for the release template:: mv bin/godot.javascript.opt.zip bin/webassembly_release.zip -And ``webassembly_debug.zip`` for the debug template:: +And `webassembly_debug.zip` for the debug template:: mv bin/godot.javascript.opt.debug.zip bin/webassembly_debug.zip @@ -68,8 +68,8 @@ The default export templates do not include threads and GDNative support for performance and compatibility reasons. See the `export page ` for more info. -You can build the export templates using the option ``threads_enabled=yes`` or -``gdnative_enabled=yes`` to enable threads or GDNative support:: +You can build the export templates using the option `threads_enabled=yes` or +`gdnative_enabled=yes` to enable threads or GDNative support:: scons platform=javascript tools=no threads_enabled=yes target=release scons platform=javascript tools=no threads_enabled=yes target=release_debug @@ -77,16 +77,16 @@ You can build the export templates using the option ``threads_enabled=yes`` or scons platform=javascript tools=no gdnative_enabled=yes target=release scons platform=javascript tools=no gdnative_enabled=yes target=release_debug -Once finished, the resulting file will be placed in the ``bin`` subdirectory. -Its name will have either the ``.threads`` or ``.gdnative`` suffix. +Once finished, the resulting file will be placed in the `bin` subdirectory. +Its name will have either the `.threads` or `.gdnative` suffix. -Finally, rename the zip archives to ``webassembly_release_threads.zip`` and -``webassembly_release_gdnative.zip`` for the release template:: +Finally, rename the zip archives to `webassembly_release_threads.zip` and +`webassembly_release_gdnative.zip` for the release template:: mv bin/godot.javascript.opt.threads.zip bin/webassembly_threads_release.zip mv bin/godot.javascript.opt.gdnative.zip bin/webassembly_gdnative_release.zip -And ``webassembly_debug_threads.zip`` and ``webassembly_debug_gdnative.zip`` for +And `webassembly_debug_threads.zip` and `webassembly_debug_gdnative.zip` for the debug template:: mv bin/godot.javascript.opt.debug.threads.zip bin/webassembly_threads_debug.zip @@ -101,8 +101,8 @@ over the native build. You can build the editor with:: scons platform=javascript tools=yes threads_enabled=yes target=release_debug -Once finished, the resulting file will be placed in the ``bin`` subdirectory. -Its name will be ``godot.javascript.opt.tools.threads.zip``. You can upload the +Once finished, the resulting file will be placed in the `bin` subdirectory. +Its name will be `godot.javascript.opt.tools.threads.zip`. You can upload the zip content to your web server and visit it with your browser to use the editor. Refer to the `export page ` for the web diff --git a/development/compiling/compiling_for_windows.rst b/development/compiling/compiling_for_windows.rst index bea8047..eff46f1 100644 --- a/development/compiling/compiling_for_windows.rst +++ b/development/compiling/compiling_for_windows.rst @@ -20,9 +20,9 @@ For compiling under Windows, the following is required: **Make sure to read "Installing Visual Studio caveats" below or you will have to run/download the installer again.** - `MinGW-w64 `__ with GCC can be used as an alternative to - Visual Studio. Be sure to install/configure it to use the ``posix`` thread model. + Visual Studio. Be sure to install/configure it to use the `posix` thread model. - `Python 3.5+ `_. - **Make sure to enable the option to add Python to the ``PATH`` in the installer.** + **Make sure to enable the option to add Python to the `PATH` in the installer.** - `SCons `_ build system. Using the latest release is recommended, especially for proper support of recent Visual Studio releases. @@ -54,23 +54,23 @@ To install SCons, open the command prompt and run the following command:: python -m pip install scons If you are prompted with the message -``Defaulting to user installation because normal site-packages is not -writeable``, you may have to run that command again using elevated +`Defaulting to user installation because normal site-packages is not +writeable`, you may have to run that command again using elevated permissions. Open a new command prompt as an Administrator then run the command -again to ensure that SCons is available from the ``PATH``. +again to ensure that SCons is available from the `PATH`. To check whether you have installed Python and SCons correctly, you can -type ``python --version`` and ``scons --version`` into a command prompt -(``cmd.exe``). +type `python --version` and `scons --version` into a command prompt +(`cmd.exe`). -If the commands above don't work, make sure to add Python to your ``PATH`` +If the commands above don't work, make sure to add Python to your `PATH` environment variable after installing it, then check again. You can do so by running the Python installer again and enabling the option -to add Python to the ``PATH``. +to add Python to the `PATH`. If SCons cannot detect your Visual Studio installation, it might be that your SCons version is too old. Update it to the latest version with -``python -m pip install --upgrade scons``. +`python -m pip install --upgrade scons`. .. _doc_compiling_for_windows_install_vs: @@ -94,7 +94,7 @@ Downloading Godot's source Refer to `doc_getting_source` for detailed instructions. The tutorial will assume from now on that you placed the source code in -``C:\godot``. +`C:\godot`. .. warning:: @@ -117,9 +117,9 @@ Selecting a compiler SCons will automatically find and use an existing Visual Studio installation. If you do not have Visual Studio installed, it will attempt to use MinGW instead. If you already have Visual Studio installed and want to -use MinGW, pass ``use_mingw=yes`` to the SCons command line. Note that MSVC +use MinGW, pass `use_mingw=yes` to the SCons command line. Note that MSVC builds cannot be performed from the MSYS2 or MinGW shells. Use either -``cmd.exe`` or PowerShell instead. +`cmd.exe` or PowerShell instead. During development, using the Visual Studio compiler is usually a better idea, as it links the Godot binary much faster than MinGW. However, MinGW can @@ -130,7 +130,7 @@ Running SCons ~~~~~~~~~~~~~ After opening a command prompt, change to the root directory of -the engine source code (using ``cd``) and type:: +the engine source code (using `cd`) and type:: C:\godot> scons platform=windows @@ -139,34 +139,34 @@ You can specify a number of CPU threads to use to speed up the build:: C:\godot> scons -j6 platform=windows 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`` +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 pywin32 being missing. You can safely ignore this warning. If all goes well, the resulting binary executable will be placed in -``C:\godot\bin\`` with the name ``godot.windows.tools.32.exe`` or -``godot.windows.tools.64.exe``. By default, SCons will build a binary matching -your CPU architecture, but this can be overridden using ``bits=64`` or -``bits=32``. +`C:\godot\bin\` with the name `godot.windows.tools.32.exe` or +`godot.windows.tools.64.exe`. By default, SCons will build a binary matching +your CPU architecture, but this can be overridden using `bits=64` or +`bits=32`. 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 make the final executable smaller and faster by adding the - SCons option ``target=release_debug``. + SCons option `target=release_debug`. If you are compiling Godot with MinGW, you can make the binary - even smaller and faster by adding the SCons option ``use_lto=yes``. + even smaller and faster by adding the SCons option `use_lto=yes`. 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 and official releases, you can enable `doc_data_paths_self_contained_mode` by creating a file called - ``._sc_`` or ``_sc_`` in the ``bin/`` folder. + `._sc_` or `_sc_` in the `bin/` folder. Development in Visual Studio ---------------------------- @@ -179,7 +179,7 @@ Folder-based editors don't require any particular setup to start working with Go codebase. To edit projects with Visual Studio they need to be set up as a solution. You can create a Visual Studio solution via SCons by running SCons with -the ``vsproj=yes`` parameter, like this:: +the `vsproj=yes` parameter, like this:: scons p=windows vsproj=yes @@ -221,12 +221,12 @@ here are some known ones: .. _mingw-w64-gcc from the AUR: https://aur.archlinux.org/packages/mingw-w64-gcc/ Before attempting the compilation, SCons will check for -the following binaries in your ``PATH`` environment variable:: +the following binaries in your `PATH` environment variable:: i686-w64-mingw32-gcc x86_64-w64-mingw32-gcc -If the binaries are not located in the ``PATH`` (e.g. ``/usr/bin``), +If the binaries are not located in the `PATH` (e.g. `/usr/bin`), you can define the following environment variables to give a hint to the build system:: @@ -274,8 +274,8 @@ with the following flags:: C:\godot> scons platform=windows tools=no target=release bits=64 If you plan on replacing the standard export templates, copy these to the -following location, replacing ```` with the version identifier -(such as ``3.1.1.stable`` or ``3.2.dev``):: +following location, replacing `` with the version identifier +(such as `3.1.1.stable` or `3.2.dev`):: %USERPROFILE%\AppData\Roaming\Godot\templates\\ @@ -293,5 +293,5 @@ here: .. image:: img/wintemplates.png You don't need to copy them in this case, just reference the resulting -files in the ``bin\`` directory of your Godot source folder, so the next +files in the `bin\` directory of your Godot source folder, so the next time you build, you will automatically have the custom templates referenced. diff --git a/development/compiling/compiling_for_x11.rst b/development/compiling/compiling_for_x11.rst index 0a369a6..1b7d3a9 100644 --- a/development/compiling/compiling_for_x11.rst +++ b/development/compiling/compiling_for_x11.rst @@ -21,14 +21,14 @@ required: - SCons 3.0+ build system. If your distribution uses Python 2 by default, or you are using a version of SCons prior to 3.1.2, you will need to change the version of Python that SCons uses by changing the shebang (the first line) - of the SCons script file to ``#! /usr/bin/python3``. - Use the command ``which scons`` to find the location of the SCons script file. + of the SCons script file to `#! /usr/bin/python3`. + Use the command `which scons` to find the location of the SCons script file. - pkg-config (used to detect the dependencies below). - X11, Xcursor, Xinerama, Xi and XRandR development libraries. - MesaGL development libraries. - ALSA development libraries. - PulseAudio development libraries. -- *Optional* - libudev (build with ``udev=yes``). +- *Optional* - libudev (build with `udev=yes`). - *Optional* - yasm (for WebM SIMD optimizations). .. seealso:: To get the Godot source code for compiling, see @@ -91,7 +91,7 @@ Distro-specific one-liners | | | | | pkg_add pkg-config py37-scons yasm | | | | -| | For audio support, you can optionally install ``pulseaudio``. | +| | For audio support, you can optionally install `pulseaudio`. | +------------------+-----------------------------------------------------------------------------------------------------------+ | **Solus** | :: | | | | @@ -108,9 +108,9 @@ Start a terminal, go to the root dir of the engine source code and type: scons -j8 platform=x11 -A good rule of thumb for the ``-j`` (*jobs*) flag, is to have at least as many +A good rule of thumb for the `-j` (*jobs*) flag, is 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. +Feel free to add the `-j` option to any SCons command you see below. If all goes well, the resulting binary executable will be placed in the "bin" subdirectory. This executable file contains the whole engine and @@ -130,17 +130,17 @@ manager. .. 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``. + SCons option `target=release_debug`. If you are compiling Godot with GCC, you can make the binary - even smaller and faster by adding the SCons option ``use_lto=yes``. + even smaller and faster by adding the SCons option `use_lto=yes`. 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 and official releases, you can enable `doc_data_paths_self_contained_mode` by creating a file called - ``._sc_`` or ``_sc_`` in the ``bin/`` folder. + `._sc_` or `_sc_` in the `bin/` folder. Compiling a headless/server build --------------------------------- @@ -213,7 +213,7 @@ here: .. image:: img/lintemplates.png You don't even need to copy them, you can just reference the resulting -files in the ``bin/`` directory of your Godot source folder, so the next +files in the `bin/` directory of your Godot source folder, so the next time you build, you automatically have the custom templates referenced. Using Clang and LLD for faster development @@ -226,13 +226,13 @@ the default GCC + GNU ld setup: faster iteration times. - Clang tends to give more useful error messages compared to GCC. -To do so, install Clang and the ``lld`` package from your distribution's package manager +To do so, install Clang and the `lld` package from your distribution's package manager then use the following SCons command:: scons platform=x11 use_llvm=yes use_lld=yes -After the build is completed, a new binary with a ``.llvm`` suffix will be -created in the ``bin/`` folder. +After the build is completed, a new binary with a `.llvm` suffix will be +created in the `bin/` folder. It's still recommended to use GCC for production builds as they can be compiled using link-time optimization, making the resulting binaries smaller and faster. @@ -247,16 +247,16 @@ often by a factor between 1.5× and 2×. Pyston can be combined with Clang and L to get even faster builds. - Download the `latest portable Pyston release `__. -- Extract the portable ``.tar.gz`` to a set location, such as ``$HOME/.local/opt/pyston/`` (create folders as needed). -- Use ``cd`` to reach the extracted Pyston folder from a terminal, - then run ``./pyston -m pip install scons`` to install SCons within Pyston. +- Extract the portable `.tar.gz` to a set location, such as `$HOME/.local/opt/pyston/` (create folders as needed). +- Use `cd` to reach the extracted Pyston folder from a terminal, + then run `./pyston -m pip install scons` to install SCons within Pyston. - To make SCons via Pyston easier to run, create a symbolic link of its wrapper - script to a location in your ``PATH`` environment variable:: + script to a location in your `PATH` environment variable:: ln -s ~/.local/opt/pyston/bin/scons ~/.local/bin/pyston-scons -- Instead of running ``scons ``, run ``pyston-scons `` +- Instead of running `scons `, run `pyston-scons ` to compile Godot. -If you can't run ``pyston-scons`` after creating the symbolic link, -make sure ``$HOME/.local/bin/`` is part of your user's ``PATH`` environment variable. +If you can't run `pyston-scons` after creating the symbolic link, +make sure `$HOME/.local/bin/` is part of your user's `PATH` environment variable. diff --git a/development/compiling/compiling_with_mono.rst b/development/compiling/compiling_with_mono.rst index b594c3d..c5c7fe9 100644 --- a/development/compiling/compiling_with_mono.rst +++ b/development/compiling/compiling_with_mono.rst @@ -20,7 +20,7 @@ The recommended method is to use **curl**'s CA (Certificate Authorities) certifi Run the following commands to download and import it. On Windows, you can run it from the Mono command line prompt (or the regular prompt if you added Mono's -``bin`` directory to your ``PATH`` environment variable):: +`bin` directory to your `PATH` environment variable):: # If using PowerShell, replace `curl` with `curl.exe` below. curl -LO https://curl.haxx.se/ca/cacert.pem @@ -34,17 +34,17 @@ Environment variables --------------------- By default, SCons will try to find Mono in the Windows Registry on Windows or -via ``pkg-config`` on other platforms. You can specify a different installation -directory by passing the ``mono_prefix`` command-line option to SCons; e.g. -``scons [...] mono_prefix=%ProgramFiles%/Mono``. +via `pkg-config` on other platforms. You can specify a different installation +directory by passing the `mono_prefix` command-line option to SCons; e.g. +`scons [...] mono_prefix=%ProgramFiles%/Mono`. -This is the directory that contains the subdirectories ``include`` and ``lib``. +This is the directory that contains the subdirectories `include` and `lib`. Enable the Mono module ---------------------- By default, the Mono module is disabled when building. To enable it, add the -option ``module_mono_enabled=yes`` to the SCons command line. +option `module_mono_enabled=yes` to the SCons command line. Generate the glue ----------------- @@ -52,27 +52,27 @@ Generate the glue Glue sources are the wrapper functions that will be called by managed methods. These source files must be generated before building your final binaries. In order to generate them, first, you must build a temporary Godot binary with the -options ``tools=yes`` and ``mono_glue=no``:: +options `tools=yes` and `mono_glue=no`:: scons p= tools=yes module_mono_enabled=yes mono_glue=no After the build finishes, you need to run the compiled executable with the -parameter ``--generate-mono-glue`` followed by the path to an output directory. -This path must be ``modules/mono/glue`` in the Godot directory:: +parameter `--generate-mono-glue` followed by the path to an output directory. +This path must be `modules/mono/glue` in the Godot directory:: --generate-mono-glue modules/mono/glue -This command will tell Godot to generate the file ``modules/mono/glue/mono_glue.gen.cpp``, -the C# solution for the Godot API at ``modules/mono/glue/GodotSharp/GodotSharp/Generated``, -and the C# solution for the editor tools at ``modules/mono/glue/GodotSharp/GodotSharpEditor/Generated``. +This command will tell Godot to generate the file `modules/mono/glue/mono_glue.gen.cpp`, +the C# solution for the Godot API at `modules/mono/glue/GodotSharp/GodotSharp/Generated`, +and the C# solution for the editor tools at `modules/mono/glue/GodotSharp/GodotSharpEditor/Generated`. Once these files are generated, you can build Godot for all the desired targets without having to repeat this process. -```` refers to the tools binary you compiled above with the Mono +`` refers to the tools binary you compiled above with the Mono module enabled. Its exact name will differ based on your system and configuration, but should be of the form -``bin/godot..tools..mono``, e.g. ``bin/godot.x11.tools.64.mono`` -or ``bin/godot.windows.tools.64.mono.exe``. Be especially aware of the **.mono** +`bin/godot..tools..mono`, e.g. `bin/godot.x11.tools.64.mono` +or `bin/godot.windows.tools.64.mono.exe`. Be especially aware of the **.mono** suffix! If you've previously compiled Godot without Mono support, you might have similarly named binaries without this suffix. These binaries can't be used to generate the Mono glue. @@ -80,7 +80,7 @@ generate the Mono glue. Notes ^^^^^ -- **Do not build your final binaries with** ``mono_glue=no``. +- **Do not build your final binaries with** `mono_glue=no`. This disables C# scripting. This option must be used only for the temporary binary that will generate the glue. Godot will print a warning at startup if it was built without the glue sources. @@ -95,7 +95,7 @@ Rebuild with Mono glue ---------------------- Once you have generated the Mono glue, you can build the final binary with -``mono_glue=yes``. This is the default value for ``mono_glue``, so you can also +`mono_glue=yes`. This is the default value for `mono_glue`, so you can also omit it. To build a Mono-enabled editor:: scons p= tools=yes module_mono_enabled=yes mono_glue=yes @@ -105,13 +105,13 @@ And Mono-enabled export templates:: scons p= tools=no module_mono_enabled=yes mono_glue=yes If everything went well, apart from the normal output, SCons should have created -the following files in the ``bin`` directory: +the following files in the `bin` directory: - If you're not linking the Mono runtime statically, the build script will place - the Mono runtime shared library (``monosgen-2.0``) next to the Godot + the Mono runtime shared library (`monosgen-2.0`) next to the Godot binary in the output directory. Make sure to include this library when distributing Godot. When targeting Android, no extra steps are required as - this library is automatically copied to ``#platform/android/java/libs`` and + this library is automatically copied to `#platform/android/java/libs` and Gradle takes care of the rest. - Unlike "classical" Godot builds, when building with the Mono module enabled (and depending on the target platform), a data directory may be created both @@ -174,56 +174,56 @@ Export templates The name of the data directory for an export template differs based on the configuration it was built with. The format is -``data.mono...``, e.g. ``data.mono.x11.32.release_debug`` or -``data.mono.windows.64.release``. +`data.mono...`, e.g. `data.mono.x11.32.release_debug` or +`data.mono.windows.64.release`. This directory must be placed with its original name next to the Godot export templates. When exporting a project, Godot will also copy this directory with -the game executable but the name will be changed to ``data_``, where -```` is the application name as specified in the project setting -``application/config/name``. +the game executable but the name will be changed to `data_`, where +`` is the application name as specified in the project setting +`application/config/name`. In the case of macOS, where the export template is compressed as a ZIP archive, the contents of the data directory can be placed in the following locations inside the ZIP archive: +-------------------------------------------------------+---------------------------------------------------------------+ -| ``bin/data.mono.../Mono/lib`` | ``/osx_template.app/Contents/Frameworks/GodotSharp/Mono/lib`` | +| `bin/data.mono.../Mono/lib` | `/osx_template.app/Contents/Frameworks/GodotSharp/Mono/lib` | +-------------------------------------------------------+---------------------------------------------------------------+ -| ``bin/data.mono.../Mono/etc`` | ``/osx_template.app/Contents/Resources/GodotSharp/Mono/etc`` | +| `bin/data.mono.../Mono/etc` | `/osx_template.app/Contents/Resources/GodotSharp/Mono/etc` | +-------------------------------------------------------+---------------------------------------------------------------+ Editor ^^^^^^ The name of the data directory for the Godot editor will always be -``GodotSharp``. The contents of this directory are the following: +`GodotSharp`. The contents of this directory are the following: -- ``Api`` -- ``Mono`` (optional) -- ``Tools`` +- `Api` +- `Mono` (optional) +- `Tools` -The ``Api`` subdirectory contains the Godot API assemblies. On macOS, if the +The `Api` subdirectory contains the Godot API assemblies. On macOS, if the Godot editor is distributed as a bundle, the contents of the data directory may be placed in the following locations: +-------------------------------------------------------+---------------------------------------------------------------+ -| ``bin/data.mono.../Api`` | ``.app/Contents/Frameworks/GodotSharp/Api`` | +| `bin/data.mono.../Api` | `.app/Contents/Frameworks/GodotSharp/Api` | +-------------------------------------------------------+---------------------------------------------------------------+ -| ``bin/data.mono.../Mono/lib`` | ``.app/Contents/Frameworks/GodotSharp/Mono/lib`` | +| `bin/data.mono.../Mono/lib` | `.app/Contents/Frameworks/GodotSharp/Mono/lib` | +-------------------------------------------------------+---------------------------------------------------------------+ -| ``bin/data.mono.../Mono/etc`` | ``.app/Contents/Resources/GodotSharp/Mono/etc`` | +| `bin/data.mono.../Mono/etc` | `.app/Contents/Resources/GodotSharp/Mono/etc` | +-------------------------------------------------------+---------------------------------------------------------------+ -| ``bin/data.mono.../Tools`` | ``.app/Contents/Frameworks/GodotSharp/Tools`` | +| `bin/data.mono.../Tools` | `.app/Contents/Frameworks/GodotSharp/Tools` | +-------------------------------------------------------+---------------------------------------------------------------+ -The ``Mono`` subdirectory is optional. It will be needed when distributing the +The `Mono` subdirectory is optional. It will be needed when distributing the editor, as issues can arise when the user-installed Mono version isn't identical -to the one the Godot editor was built with. Pass ``copy_mono_root=yes`` to SCons +to the one the Godot editor was built with. Pass `copy_mono_root=yes` to SCons when building the editor in order to create this folder and its contents. -The ``Tools`` subdirectory contains tools required by the editor, like the -``GodotTools`` assemblies and its dependencies. +The `Tools` subdirectory contains tools required by the editor, like the +`GodotTools` assemblies and its dependencies. Building the Mono runtime ------------------------- @@ -251,7 +251,7 @@ Once you've built Mono, you can proceed to build Godot with the instructions described in this page and the `Compiling for Android` page. Make sure to let SCons know about the location of the Mono runtime you've just built, e.g.: -``scons [...] mono_prefix="$HOME/mono-installs/android-armeabi-v7a-release"`` +`scons [...] mono_prefix="$HOME/mono-installs/android-armeabi-v7a-release"` (This path may be different on your system). Targeting iOS @@ -261,7 +261,7 @@ Once you've built Mono, you can proceed to build Godot with the instructions described in this page and the `Compiling for iOS` page. Make sure to let SCons know about the location of the Mono runtime you've just built, e.g.: -``scons [...] mono_prefix="$HOME/mono-installs/ios-arm64-release"`` +`scons [...] mono_prefix="$HOME/mono-installs/ios-arm64-release"` (This path may be different on your system). After building Godot for each architecture, you will notice SCons has @@ -282,7 +282,7 @@ The last three are only for iOS devices and are not available for the iOS simula These libraries must be put in universal (multi-architecture) "fat" files to be distributed with the export templates. -The following bash script will create the "fat" libraries in the directory ``#bin/ios/iphone-mono-libs``: +The following bash script will create the "fat" libraries in the directory `#bin/ios/iphone-mono-libs`: :: @@ -298,8 +298,8 @@ The following bash script will create the "fat" libraries in the directory ``#bi lipo -create bin/libmono-icall-table.iphone.arm64.a -output bin/ios/iphone-mono-libs/libmono-icall-table.iphone.fat.a lipo -create bin/libmono-ilgen.iphone.arm64.a -output bin/ios/iphone-mono-libs/libmono-ilgen.iphone.fat.a -The ``iphone-mono-libs`` folder must be distributed with the export templates. -The Godot editor will look for the libraries in ``/iphone-mono-libs/lib.iphone.fat.a``. +The `iphone-mono-libs` folder must be distributed with the export templates. +The Godot editor will look for the libraries in `/iphone-mono-libs/lib.iphone.fat.a`. Targeting WebAssembly --------------------- @@ -310,29 +310,29 @@ Once you've built Mono, you can proceed to build Godot with the instructions described in this page and the `Compiling for the Web` page. Make sure to let SCons know about the location of the Mono runtime you've just built, e.g.: -``scons [...] mono_prefix="$HOME/mono-installs/wasm-runtime-release"`` +`scons [...] mono_prefix="$HOME/mono-installs/wasm-runtime-release"` (This path may be different on your system). Base Class Library ------------------ The export templates must also include the BCL (Base Class Library) for each target platform. -Godot looks for the BCL folder at ``/bcl/``, -where ```` is the same name passed to the SCons ``platform`` option, -e.g.: ``/bcl/windows``, ``/bcl/javascript``. +Godot looks for the BCL folder at `/bcl/`, +where `` is the same name passed to the SCons `platform` option, +e.g.: `/bcl/windows`, `/bcl/javascript`. Alternatively, Godot will look for them in the following locations: +-------------------+---------------------------------+ -| Android | ``/bcl/monodroid`` | +| Android | `/bcl/monodroid` | +-------------------+---------------------------------+ -| iOS | ``/bcl/monotouch`` | +| iOS | `/bcl/monotouch` | +-------------------+---------------------------------+ -| WebAssembly | ``/bcl/wasm`` | +| WebAssembly | `/bcl/wasm` | +-------------------+---------------------------------+ -| Linux and macOS | ``/bcl/net_4_x`` | +| Linux and macOS | `/bcl/net_4_x` | +-------------------+---------------------------------+ -| Windows | ``/bcl/net_4_x_win`` | +| Windows | `/bcl/net_4_x_win` | +-------------------+---------------------------------+ As of now, we're assuming the same BCL profile can be used for both Linux and macOS, @@ -340,7 +340,7 @@ but this may change in the future as they're not guaranteed to be the same (as is the case with the Windows BCL). If the target platform is the same as the platform of the Godot editor, -then the editor will use the BCL it's running on (``/Mono/lib/mono/4.5``) +then the editor will use the BCL it's running on (`/Mono/lib/mono/4.5`) if it cannot find the BCL in the export templates. AOT cross-compilers @@ -350,13 +350,13 @@ To perform ahead-of-time (AOT) compilation for other platforms, Godot needs to h access to the Mono cross-compilers for that platform and architecture. Godot will look for the cross-compiler executable in the AOT compilers folder. -The location of this folder is ``/Tools/aot-compilers/``. +The location of this folder is `/Tools/aot-compilers/`. In order to build the cross-compilers we recommend using these `build scripts `_. After building them, copy the executable to the Godot AOT compilers directory. The -executable name is ``-mono-sgen``, e.g.: ``aarch64-apple-darwin-mono-sgen``. +executable name is `-mono-sgen`, e.g.: `aarch64-apple-darwin-mono-sgen`. Command-line options -------------------- @@ -371,7 +371,7 @@ the Mono module: - **mono_glue**\ =\ **yes** | no - Whether to include the glue source files in the build - and define ``MONO_GLUE_DISABLED`` as a preprocessor macro. + and define `MONO_GLUE_DISABLED` as a preprocessor macro. - **mono_prefix**\ =path diff --git a/development/compiling/compiling_with_script_encryption_key.rst b/development/compiling/compiling_with_script_encryption_key.rst index e2f8ad6..92a863c 100644 --- a/development/compiling/compiling_with_script_encryption_key.rst +++ b/development/compiling/compiling_with_script_encryption_key.rst @@ -34,7 +34,7 @@ Step by step openssl rand -hex 32 > godot.gdkey - The output in ``godot.gdkey`` should be similar to: + The output in `godot.gdkey` should be similar to: :: @@ -54,7 +54,7 @@ bash Linux/macOS bat Windows (cmd) -``` set SCRIPT_AES256_ENCRYPTION_KEY=your_generated_key ```` +``` set SCRIPT_AES256_ENCRYPTION_KEY=your_generated_key ``` bat Windows (PowerShell) diff --git a/development/compiling/cross-compiling_for_ios_on_linux.rst b/development/compiling/cross-compiling_for_ios_on_linux.rst index df219e6..a159be6 100644 --- a/development/compiling/cross-compiling_for_ios_on_linux.rst +++ b/development/compiling/cross-compiling_for_ios_on_linux.rst @@ -29,8 +29,8 @@ Requirements - `XCode with the iOS SDK `__ (a dmg image) - `Clang >= 3.5 `__ for your development - machine installed and in the ``PATH``. It has to be version >= 3.5 - to target ``arm64`` architecture. + machine installed and in the `PATH`. It has to be version >= 3.5 + to target `arm64` architecture. - `Fuse `__ for mounting and umounting the dmg image. - `darling-dmg `__, which @@ -109,7 +109,7 @@ Build cctools: $ ./build.sh /path/iPhoneOS9.1.sdk.tar.xz arm64 Copy the tools to a nicer place. Note that the SCons scripts for -building will look under ``usr/bin`` inside the directory you provide +building will look under `usr/bin` inside the directory you provide for the toolchain binaries, so you must copy to such subdirectory, akin to the following commands: @@ -119,7 +119,7 @@ to the following commands: $ cp -r target/bin /home/user/iostoolchain/usr/ Now you should have the iOS toolchain binaries in -``/home/user/iostoolchain/usr/bin``. +`/home/user/iostoolchain/usr/bin`. Compiling Godot for iPhone -------------------------- @@ -129,7 +129,7 @@ environment: the built toolchain and the iPhoneOS SDK directory. Those can stay anywhere you want since you have to provide their paths to the SCons build command. -For the iPhone platform to be detected, you need the ``OSXCROSS_IOS`` +For the iPhone platform to be detected, you need the `OSXCROSS_IOS` environment variable defined to anything. :: @@ -147,9 +147,9 @@ way, with some additional arguments to provide the correct paths: Producing fat binaries ~~~~~~~~~~~~~~~~~~~~~~ -Apple requires a fat binary with both architectures (``armv7`` and -``arm64``) in a single file. To do this, use the -``arm-apple-darwin11-lipo`` executable. The following example assumes +Apple requires a fat binary with both architectures (`armv7` and +`arm64`) in a single file. To do this, use the +`arm-apple-darwin11-lipo` executable. The following example assumes you are in the root Godot source directory: :: @@ -159,4 +159,4 @@ you are in the root Godot source directory: $ /path/to/iostoolchain/usr/bin/arm-apple-darwin11-lipo -create bin/libgodot_arkit_module.iphone.opt.debug.arm.a bin/libgodot_arkit_module.iphone.opt.debug.arm64.a -output bin/libgodot_arkit_module.iphone.debug.fat.a -Then you will have iOS fat binaries in ``bin`` directory. +Then you will have iOS fat binaries in `bin` directory. diff --git a/development/compiling/getting_source.rst b/development/compiling/getting_source.rst index 647e58f..81f9721 100644 --- a/development/compiling/getting_source.rst +++ b/development/compiling/getting_source.rst @@ -13,20 +13,20 @@ and compiling Godot, you need to actually download the Godot source code. The source code is available on `GitHub `__ and while you can manually download it via the website, in general you want to -do it via the ``git`` version control system. +do it via the `git` version control system. If you are compiling in order to make contributions or pull requests, you should follow the instructions from the `Pull Request workflow `. -If you don't know much about ``git`` yet, there are a great number of +If you don't know much about `git` yet, there are a great number of `tutorials `__ available on various websites. -In general, you need to install ``git`` and/or one of the various GUI clients. +In general, you need to install `git` and/or one of the various GUI clients. Afterwards, to get the latest development version of the Godot source code -(the unstable ``master`` branch), you can use ``git clone``. +(the unstable `master` branch), you can use `git clone`. -If you are using the ``git`` command line client, this is done by entering +If you are using the `git` command line client, this is done by entering the following in a terminal: :: @@ -39,8 +39,8 @@ For any stable release, visit the `release page `. diff --git a/development/compiling/introduction_to_the_buildsystem.rst b/development/compiling/introduction_to_the_buildsystem.rst index 919e0f7..3345420 100644 --- a/development/compiling/introduction_to_the_buildsystem.rst +++ b/development/compiling/introduction_to_the_buildsystem.rst @@ -44,8 +44,8 @@ Please refer to the documentation for `doc_compiling_for_android`, `doc_compiling_for_uwp`, `doc_compiling_for_web`, `doc_compiling_for_windows` and `doc_compiling_for_x11`. -Note that for **Windows/Visual Studio**, you need to use ``x86_x64 Cross Tools -Command Prompt for VS 2017`` or similar, depending on your install, instead of +Note that for **Windows/Visual Studio**, you need to use `x86_x64 Cross Tools +Command Prompt for VS 2017` or similar, depending on your install, instead of the standard Windows command prompt to enter the commands below. Platform selection @@ -56,11 +56,11 @@ for. If not detected, the platform will simply not appear on the list of available platforms. The build requirements for each platform are described in the rest of this tutorial section. -SCons is invoked by just calling ``scons``. If no platform is specified, +SCons is invoked by just calling `scons`. If no platform is specified, SCons will detect the target platform automatically based on the host platform. It will then start building for the target platform right away. -To list the available target platforms, use ``scons platform=list``:: +To list the available target platforms, use `scons platform=list`:: scons platform=list scons: Reading SConscript files ... @@ -74,15 +74,15 @@ To list the available target platforms, use ``scons platform=list``:: Please run SCons again and select a valid platform: platform= -To build for a platform (for example, x11), run with the ``platform=`` (or -``p=`` to make it short) argument: +To build for a platform (for example, x11), run with the `platform=` (or +`p=` to make it short) argument: :: scons platform=x11 This will start the build process, which will take a while. If you want -SCons to build faster, use the ``-j `` parameter to specify how many +SCons to build faster, use the `-j ` parameter to specify how many cores will be used for the build. Or leave it using one core, so you can use your computer for something else :) @@ -95,7 +95,7 @@ Example for using 4 cores: Resulting binary ---------------- -The resulting binaries will be placed in the ``bin/`` subdirectory, +The resulting binaries will be placed in the `bin/` subdirectory, generally with this naming convention:: godot..[opt].[tools/debug].[extension] @@ -152,16 +152,16 @@ Target controls optimization and debug flags. Each mode means: reports errors). Official editor binaries use this configuration. - **release**: Build without symbols, with optimization and with little to no runtime checks. This target can't be used together with - ``tools=yes``, as the editor requires some debug functionality and run-time + `tools=yes`, as the editor requires some debug functionality and run-time checks to run. :: scons platform= target=debug/release_debug/release -This flag appends the ``.debug`` suffix (for debug), or ``.tools`` (for debug +This flag appends the `.debug` suffix (for debug), or `.tools` (for debug with tools enabled). When optimization is enabled (release), it appends -the ``.opt`` suffix. +the `.opt` suffix. Bits ---- @@ -178,8 +178,8 @@ else. scons platform= bits=default/32/64 -This flag appends ``.32`` or ``.64`` suffixes to resulting binaries when -relevant. If ``bits=default`` is used, the suffix will match the detected +This flag appends `.32` or `.64` suffixes to resulting binaries when +relevant. If `bits=default` is used, the suffix will match the detected architecture. .. _doc_buildsystem_custom_modules: @@ -190,10 +190,10 @@ Custom modules It's possible to compile modules residing outside of Godot's directory tree, along with the built-in modules. -A ``custom_modules`` build option can be passed to the command line before +A `custom_modules` build option can be passed to the command line before compiling. The option represents a comma-separated list of directory paths containing a collection of independent C++ modules that can be seen as C++ -packages, just like the built-in ``modules/`` directory. +packages, just like the built-in `modules/` directory. For instance, it's possible to provide both relative, absolute, and user directory paths containing such modules: @@ -216,10 +216,10 @@ Cleaning generated files ------------------------ Sometimes, you may encounter an error due to generated files being present. You -can remove them by using ``scons --clean ``, where ```` is the +can remove them by using `scons --clean `, where `` is the list of build options you've used to build Godot previously. -Alternatively, you can use ``git clean -fixd`` which will clean build artifacts +Alternatively, you can use `git clean -fixd` which will clean build artifacts for all platforms and configurations. Beware, as this will remove all untracked and ignored files in the repository. Don't run this command if you have uncommitted work! @@ -231,7 +231,7 @@ There are several other build options that you can use to configure the way Godot should be built (compiler, debug options, etc.) as well as the features to include/disable. -Check the output of ``scons --help`` for details about each option for +Check the output of `scons --help` for details about each option for the version you are willing to compile. .. _doc_overriding_build_options: @@ -242,7 +242,7 @@ Overriding the build options Using a file ^^^^^^^^^^^^ -The default ``custom.py`` file can be created at the root of the Godot Engine +The default `custom.py` file can be created at the root of the Godot Engine source to initialize any SCons build options passed via the command line: .. code-block:: python @@ -261,10 +261,10 @@ time it takes to build the engine. See `doc_optimizing_for_size` page for more d You can use the online `Godot build options generator `__ - to generate a ``custom.py`` file containing SCons options. + to generate a `custom.py` file containing SCons options. You can then save this file and place it at the root of your Godot source directory. -Another custom file can be specified explicitly with the ``profile`` command +Another custom file can be specified explicitly with the `profile` command line option, both overriding the default build configuration: .. code-block:: shell @@ -291,11 +291,11 @@ It's also possible to override the options conditionally: Using the SCONSFLAGS ^^^^^^^^^^^^^^^^^^^^ -``SCONSFLAGS`` is an environment variable which is used by the SCons to set the +`SCONSFLAGS` is an environment variable which is used by the SCons to set the options automatically without having to supply them via the command line. For instance, you may want to build Godot in parallel with the aforementioned -``-j`` option for all the future builds: +`-j` option for all the future builds: bash Linux/macOS @@ -344,12 +344,12 @@ To create those yourself, follow the instructions detailed for each platform in this same tutorial section. Each platform explains how to create its own template. -The ``version.txt`` file should contain the corresponding Godot version +The `version.txt` file should contain the corresponding Godot version identifier. This file is used to install export templates in a version-specific directory to avoid conflicts. For instance, if you are building export templates -for Godot 3.1.1, ``version.txt`` should contain ``3.1.1.stable`` on the first -line (and nothing else). This version identifier is based on the ``major``, -``minor``, ``patch`` (if present) and ``status`` lines of the +for Godot 3.1.1, `version.txt` should contain `3.1.1.stable` on the first +line (and nothing else). This version identifier is based on the `major`, +`minor`, `patch` (if present) and `status` lines of the `version.py file in the Godot Git repository `__. If you are developing for multiple platforms, macOS is definitely the most diff --git a/development/compiling/optimizing_for_size.rst b/development/compiling/optimizing_for_size.rst index 8681aa7..327b280 100644 --- a/development/compiling/optimizing_for_size.rst +++ b/development/compiling/optimizing_for_size.rst @@ -28,14 +28,14 @@ Stripping binaries - **Performed in official builds:** Yes If you build Windows (MinGW), Linux or macOS binaries from source, remember to -strip debug symbols from binaries by installing the ``strip`` package from your +strip debug symbols from binaries by installing the `strip` package from your distribution then running: :: strip path/to/godot.binary -On Windows, ``strip.exe`` is included in most MinGW toolchain setups. +On Windows, `strip.exe` is included in most MinGW toolchain setups. This will reduce the size of compiled binaries by a factor between 5× and 10×. The downside is that crash backtraces will no longer provide accurate information @@ -46,7 +46,7 @@ function names (this does not affect the built-in GDScript profiler). .. 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`` + and platforms such as Android and HTML5. Instead, pass `debug_symbols=no` on the SCons command line when compiling. Optimizing for size instead of speed @@ -57,7 +57,7 @@ Optimizing for size instead of speed - **Performed in official builds:** Yes, but only for HTML5 Godot 3.1 onwards allows compiling using size optimizations (instead of speed). -To enable this, set the ``optimize`` flag to ``size``: +To enable this, set the `optimize` flag to `size`: :: @@ -84,9 +84,9 @@ and MSVC compilers: Linking becomes much slower and more RAM-consuming with this option, so it should be used only for release builds: -- When compiling the ``master`` branch, you need to have at least 8 GB of RAM +- When compiling the `master` branch, you need to have at least 8 GB of RAM available for successful linking with LTO enabled. -- When compiling the ``3.x`` branch, you need to have at least 6 GB of RAM +- When compiling the `3.x` branch, you need to have at least 6 GB of RAM available for successful linking with LTO enabled. Disabling 3D @@ -173,7 +173,7 @@ might want to keep networking-related modules, regex support, or theora/webm to play videos). Alternatively, you can supply a list of disabled modules by creating -``custom.py`` at the root of the source, with the contents similar to the +`custom.py` at the root of the source, with the contents similar to the following: .. code-block:: python diff --git a/development/cpp/binding_to_external_libraries.rst b/development/cpp/binding_to_external_libraries.rst index 4509f78..0bc1a5e 100644 --- a/development/cpp/binding_to_external_libraries.rst +++ b/development/cpp/binding_to_external_libraries.rst @@ -77,7 +77,7 @@ need to be created: .. important:: These files must be in the top-level folder of your module (next to your - ``SCsub`` and ``config.py`` files) for the module to be registered properly. + `SCsub` and `config.py` files) for the module to be registered properly. These files should contain the following: @@ -106,7 +106,7 @@ These files should contain the following: // Nothing to do here in this example. } -Next, you need to create a ``SCsub`` file so the build system compiles +Next, you need to create a `SCsub` file so the build system compiles this module: .. code-block:: python @@ -225,4 +225,4 @@ You can now use your newly created module from any script: var is_spoken = t.say_text(script) print('is_spoken: ', is_spoken) -And the output will be ``is_spoken: True`` if the text is spoken. +And the output will be `is_spoken: True` if the text is spoken. diff --git a/development/cpp/common_engine_methods_and_macros.rst b/development/cpp/common_engine_methods_and_macros.rst index e59f718..0bb397f 100644 --- a/development/cpp/common_engine_methods_and_macros.rst +++ b/development/cpp/common_engine_methods_and_macros.rst @@ -34,8 +34,8 @@ described below. Format a string --------------- -The ``vformat()`` function returns a formatted `String`. It behaves -in a way similar to C's ``sprintf()``: +The `vformat()` function returns a formatted `String`. It behaves +in a way similar to C's `sprintf()`: .. code-block:: cpp @@ -48,7 +48,7 @@ in a way similar to C's ``sprintf()``: // to a method that expects a `const char *` instead of a String. vformat("My name is %s.", "Godette").c_str(); -In most cases, try to use ``vformat()`` instead of string concatenation as it +In most cases, try to use `vformat()` instead of string concatenation as it makes for more readable code. Convert an integer or float to a string @@ -69,11 +69,11 @@ Internationalize a string There are two types of internationalization in Godot's codebase: -- ``TTR()``: **Editor ("tools") translations** will only be processed in the +- `TTR()`: **Editor ("tools") translations** will only be processed in the editor. If a user uses the same text in one of their projects, it won't be translated if they provide a translation for it. When contributing to the engine, this is generally the macro you should use for localizable strings. -- ``RTR()``: **Run-time translations** will be automatically localized in +- `RTR()`: **Run-time translations** will be automatically localized in projects if they provide a translation for the given string. This kind of translation shouldn't be used in editor-only code. @@ -85,7 +85,7 @@ There are two types of internationalization in Godot's codebase: TTR("Exit the editor?"); To insert placeholders in localizable strings, wrap the localization macro in a -``vformat()`` call as follows: +`vformat()` call as follows: .. code-block:: cpp @@ -94,16 +94,16 @@ To insert placeholders in localizable strings, wrap the localization macro in a .. note:: - When using ``vformat()`` and a translation macro together, always wrap the - translation macro in ``vformat()``, not the other way around. Otherwise, the + When using `vformat()` and a translation macro together, always wrap the + translation macro in `vformat()`, not the other way around. Otherwise, the string will never match the translation as it will have the placeholder already replaced when it's passed to TranslationServer. Clamp a value ------------- -Godot provides macros for clamping a value with a lower bound (``MAX``), an -upper bound (``MIN``) or both (``CLAMP``): +Godot provides macros for clamping a value with a lower bound (`MAX`), an +upper bound (`MIN`) or both (`CLAMP`): .. code-block:: cpp @@ -114,8 +114,8 @@ upper bound (``MIN``) or both (``CLAMP``): MIN(2, a); // 2 CLAMP(a, 10, 30); // 10 -This works with any type that can be compared to other values (like ``int`` and -``float``). +This works with any type that can be compared to other values (like `int` and +`float`). Microbenchmarking ----------------- @@ -132,12 +132,12 @@ use this snippet: uint64_t end = OS::get_singleton()->get_ticks_usec(); print_line(vformat("Snippet took %d microseconds", end - begin)); -This will print the time spent between the ``begin`` declaration and the ``end`` +This will print the time spent between the `begin` declaration and the `end` declaration. .. note:: - You may have to ``#include "core/os/os.h"`` if it's not present already. + You may have to `#include "core/os/os.h"` if it's not present already. When opening a pull request, make sure to remove this snippet as well as the include if it wasn't there previously. @@ -167,8 +167,8 @@ repetition: // Returns the value of the editor setting. EDITOR_GET("section/subsection/value"); -It's recommended to use ``GLOBAL_DEF``/``EDITOR_DEF`` only once per setting and -use ``GLOBAL_GET``/``EDITOR_GET`` in all other places where it's referenced. +It's recommended to use `GLOBAL_DEF`/`EDITOR_DEF` only once per setting and +use `GLOBAL_GET`/`EDITOR_GET` in all other places where it's referenced. Error macros ------------ @@ -178,8 +178,8 @@ Godot features many error macros to make error reporting more convenient. .. 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``. + built-in `assert()` function. An error is reached if the condition inside + evaluates to `true`, not `false`. .. note:: @@ -190,7 +190,7 @@ Godot features many error macros to make error reporting more convenient. the invalid value in question to ease debugging. For internal error checking where displaying a human-readable message isn't - necessary, remove ``_MSG`` at the end of the macro name and don't supply a + necessary, remove `_MSG` at the end of the macro name and don't supply a message argument. Also, always try to return processable data so the engine can keep running @@ -241,6 +241,6 @@ Godot features many error macros to make error reporting more convenient. in Godot's codebase for more information about each error macro. Some functions return an error code (materialized by a return type of - ``Error``). This value can be returned directly from an error macro. + `Error`). This value can be returned directly from an error macro. See the list of available error codes in `core/error_list.h `__. diff --git a/development/cpp/configuring_an_ide/android_studio.rst b/development/cpp/configuring_an_ide/android_studio.rst index 6422144..cbcd52e 100644 --- a/development/cpp/configuring_an_ide/android_studio.rst +++ b/development/cpp/configuring_an_ide/android_studio.rst @@ -20,7 +20,7 @@ Importing the project Android Studio's welcome window. -- Navigate to ``/platform/android/java`` and select the ``settings.gradle`` file. +- Navigate to `/platform/android/java` and select the `settings.gradle` file. - Android Studio will import and index the project. - To build the project, follow the `compiling instructions `. diff --git a/development/cpp/configuring_an_ide/clion.rst b/development/cpp/configuring_an_ide/clion.rst index 83dae9b..bdd3c53 100644 --- a/development/cpp/configuring_an_ide/clion.rst +++ b/development/cpp/configuring_an_ide/clion.rst @@ -9,22 +9,22 @@ CLion Importing the project --------------------- -CLion requires a ``CMakeLists.txt`` file as a project file, which is problematic +CLion requires a `CMakeLists.txt` file as a project file, which is problematic for Godot because it uses the SCons buildsystem instead of CMake. However, -there is a ``CMakeLists.txt`` configuration for `Android Studio ` +there is a `CMakeLists.txt` configuration for `Android Studio ` which can also be used by CLion. - From the CLion's welcome window choose the option to import an existing project. If you've already opened another project, choose **File > Open** from the top menu. -- Navigate to ``/platform/android/java/nativeSrcsConfigs`` (the - ``CMakeLists.txt`` file is located there) and select it (but *not* the - ``CMakeLists.txt`` file itself), then click **OK**. +- Navigate to `/platform/android/java/nativeSrcsConfigs` (the + `CMakeLists.txt` file is located there) and select it (but *not* the + `CMakeLists.txt` file itself), then click **OK**. .. figure:: img/clion_1_open.png :align: center - The folder containing the ``CMakeLists.txt`` file. + The folder containing the `CMakeLists.txt` file. - If this popup window appears, select **This Window** to open the project: @@ -49,9 +49,9 @@ Debugging the project Since CLion does not support SCons, you won't be able to compile, launch, and debug Godot from CLion in one step. You will first need to `compile godot yourself `__ and run the binary without CLion. You will then be able to debug Godot by using the `Attach to process `__ feature. -- Run the compilation in debug mode by entering ``scons``. +- Run the compilation in debug mode by entering `scons`. -- Run the binary you have created (in the bin directory). If you want to debug a specific project, run the binary with the following arguments : ``--editor --path path/to/your/godot/project``. To run the project instead of editing it, remove the ``--editor`` argument. +- Run the binary you have created (in the bin directory). If you want to debug a specific project, run the binary with the following arguments : `--editor --path path/to/your/godot/project`. To run the project instead of editing it, remove the `--editor` argument. - In CLion, go to **Run > Attach to Process...** @@ -68,4 +68,4 @@ You can now use the debugging tools from CLion. .. 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. + 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/code_blocks.rst b/development/cpp/configuring_an_ide/code_blocks.rst index 9140592..1946514 100644 --- a/development/cpp/configuring_an_ide/code_blocks.rst +++ b/development/cpp/configuring_an_ide/code_blocks.rst @@ -26,9 +26,9 @@ Click Next, to pass the welcome to the new empty project wizard. :figclass: figure-w480 :align: center -The project file should be created in the root of the cloned project folder. To achieve this, first, ensure that the **Project title** is the same as the folder name that Godot was cloned into. Unless you cloned the project into a folder with a different name, this will be ``godot``. +The project file should be created in the root of the cloned project folder. To achieve this, first, ensure that the **Project title** is the same as the folder name that Godot was cloned into. Unless you cloned the project into a folder with a different name, this will be `godot`. -Second, ensure that the **Folder to create project in** is the folder you ran the Git clone command from, not the ``godot`` project folder. Confirm that the **Resulting filename** field will create the project file in the root of the cloned project folder. +Second, ensure that the **Folder to create project in** is the folder you ran the Git clone command from, not the `godot` project folder. Confirm that the **Resulting filename** field will create the project file in the root of the cloned project folder. .. figure:: img/code_blocks_project_title_and_location.png :figclass: figure-w480 @@ -61,9 +61,9 @@ The next step is to change the build options. Right-click on the new project and :figclass: figure-w480 :align: center -Select the **"Make" commands** tab and remove all the existing commands for all the build targets. For each build target enter the **SCons** command for creating the desired build in the **Build project/target** field. The minimum is ``scons``. For details on the **SCons** build options, see `doc_introduction_to_the_buildsystem`. It's also useful to add the ``scons --clean`` command in the **Clean project/target** field to the project's default commmands. +Select the **"Make" commands** tab and remove all the existing commands for all the build targets. For each build target enter the **SCons** command for creating the desired build in the **Build project/target** field. The minimum is `scons`. For details on the **SCons** build options, see `doc_introduction_to_the_buildsystem`. It's also useful to add the `scons --clean` command in the **Clean project/target** field to the project's default commmands. -If you're using Windows, all the commands need to be preceded with ``cmd /c`` to iniitalize the command interpreter. +If you're using Windows, all the commands need to be preceded with `cmd /c` to iniitalize the command interpreter. .. figure:: img/code_blocks_scons_minimum.png :figclass: figure-w480 @@ -84,7 +84,7 @@ Code::Blocks should now be configured to build Godot; so either select **Build > Configuring the run ------------------- -Once **SCons** has successfully built the desired target, reopen the project **Properties...** and select the **Build targets** tab. In the **Output filename** field, browse to the ``bin`` folder and select the compiled file. +Once **SCons** has successfully built the desired target, reopen the project **Properties...** and select the **Build targets** tab. In the **Output filename** field, browse to the `bin` folder and select the compiled file. Deselect the **Auto-generate filename prefix** and **Auto-generate filename extension** options. @@ -94,7 +94,7 @@ Deselect the **Auto-generate filename prefix** and **Auto-generate filename exte Code::Blocks should now be configured to run your compiled Godot executable; so either select **Build > Run**, click the green arrow button, or press :kbd:`Ctrl + F10`. -There are two additional points worth noting. First, if required, the **Execution working dir** field can be used to test specific projects, by setting it to the folder containing the ``project.godot`` file. Second, the **Build targets** tab can be used to add and remove build targets for working with and creating different builds. +There are two additional points worth noting. First, if required, the **Execution working dir** field can be used to test specific projects, by setting it to the folder containing the `project.godot` file. Second, the **Build targets** tab can be used to add and remove build targets for working with and creating different builds. Adding files to the project --------------------------- diff --git a/development/cpp/configuring_an_ide/index.rst b/development/cpp/configuring_an_ide/index.rst index 82d7154..aa2158a 100644 --- a/development/cpp/configuring_an_ide/index.rst +++ b/development/cpp/configuring_an_ide/index.rst @@ -4,7 +4,7 @@ Configuring an IDE We assume that you have already `cloned `_ and `compiled ` Godot. -You can easily develop Godot with any text editor and by invoking ``scons`` +You can easily develop Godot with any text editor and by invoking `scons` on the command line, but if you want to work with an IDE (Integrated Development Environment), here are setup instructions for some popular ones: diff --git a/development/cpp/configuring_an_ide/kdevelop.rst b/development/cpp/configuring_an_ide/kdevelop.rst index a3c2561..c77da24 100644 --- a/development/cpp/configuring_an_ide/kdevelop.rst +++ b/development/cpp/configuring_an_ide/kdevelop.rst @@ -76,8 +76,8 @@ Debugging the project - Click **Add** to create a new launch configuration. - Select **Executable** option and specify the path to your executable located in - the ``/bin`` folder. The name depends on your build configuration, - e.g. ``godot.x11.tools.64`` for 64-bit X11 platform with ``tools`` enabled. + the `/bin` folder. The name depends on your build configuration, + e.g. `godot.x11.tools.64` for 64-bit X11 platform with `tools` enabled. .. figure:: img/kdevelop_configlaunches2.png :figclass: figure-w480 diff --git a/development/cpp/configuring_an_ide/qt_creator.rst b/development/cpp/configuring_an_ide/qt_creator.rst index 5d6b9d1..d8903b2 100644 --- a/development/cpp/configuring_an_ide/qt_creator.rst +++ b/development/cpp/configuring_an_ide/qt_creator.rst @@ -22,8 +22,8 @@ Importing the project - Next, you can choose which folders and files will be visible to the project. While C/C++ files are added automatically, other extensions can be potentially useful: - ``*.glsl`` for shader files, ``*.py`` for buildsystem files, - ``*.java`` for Android platform development, ``*.mm`` for macOS platform development. + `*.glsl` for shader files, `*.py` for buildsystem files, + `*.java` for Android platform development, `*.mm` for macOS platform development. .. figure:: img/qtcreator-apply-import-filter.png :figclass: figure-w480 @@ -38,7 +38,7 @@ Importing the project - Finish the import. -- Open the ``project_name.includes`` file and add a line containing ``.`` to it +- Open the `project_name.includes` file and add a line containing `.` to it to correctly enable the code completion. .. figure:: img/qtcreator-project-name-includes.png @@ -46,7 +46,7 @@ Importing the project :align: center - From the left-side menu select **Projects** and open the **Build** tab. -- Delete the predefined ``make`` build step. +- Delete the predefined `make` build step. .. figure:: img/qtcreator-projects-build.png :figclass: figure-w480 @@ -65,8 +65,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`` - is not in your ``PATH`` environment variable. In this case, you'll have to specify the +.. 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. Debugging the project @@ -74,11 +74,11 @@ Debugging the project - From the left-side menu select **Projects** and open the **Run** tab. - Under **Executable** specify the path to your executable located in - the ``/bin`` folder. The name depends on your build configuration, - e.g. ``godot.x11.tools.64`` for 64-bit X11 platform with ``tools`` enabled. - You can use ``%{buildDir}`` to reference the project root, e.g: ``%{buildDir}/bin/godot.x11.opt.tools.64``. + the `/bin` folder. The name depends on your build configuration, + e.g. `godot.x11.tools.64` for 64-bit X11 platform with `tools` enabled. + You can use `%{buildDir}` to reference the project root, e.g: `%{buildDir}/bin/godot.x11.opt.tools.64`. - If you want to run a specific project, specify its root folder under **Working directory**. -- If you want to run the editor, add ``-e`` to the **Command line arguments** field. +- If you want to run the editor, add `-e` to the **Command line arguments** field. .. figure:: img/qtcreator-run-command.png :figclass: figure-w480 diff --git a/development/cpp/configuring_an_ide/visual_studio.rst b/development/cpp/configuring_an_ide/visual_studio.rst index 471ed4a..8be1c3c 100644 --- a/development/cpp/configuring_an_ide/visual_studio.rst +++ b/development/cpp/configuring_an_ide/visual_studio.rst @@ -15,8 +15,8 @@ Visual Studio requires a solution file to work on a project. While Godot does no with the solution file, it can be generated using SCons. - Navigate to the Godot root folder and open a Command Prompt or PowerShell window. -- Run ``scons platform=windows vsproj=yes`` to generate the solution. -- You can now open the project by double-clicking on the ``godot.sln`` in the project root +- Run `scons platform=windows vsproj=yes` to generate the solution. +- You can now open the project by double-clicking on the `godot.sln` in the project root or by using the **Open a project or solution** option inside of the Visual Studio. - Use the **Build** top menu to build the project. @@ -45,9 +45,9 @@ project manager opens a project, the initial process is terminated and the debug :align: center - Open the **Debugging** section and under **Command Arguments** add two new arguments: - the ``-e`` flag opens the editor instead of the project manager, and the ``--path`` argument + the `-e` flag opens the editor instead of the project manager, and the `--path` argument tells the executable to open the specified project (must be provided as an *absolute* path - to the project root, not the ``project.godot`` file). + to the project root, not the `project.godot` file). .. figure:: img/vs_3_debug_command_line.png :align: center @@ -58,7 +58,7 @@ To learn more about command line arguments, refer to the Even if you start the project without a debugger attached it can still be connected to the running process using **Debug > Attach to Process...** menu. -To check that everything is working, put a breakpoint in ``main.cpp`` and press :kbd:`F5` to +To check that everything is working, put a breakpoint in `main.cpp` and press :kbd:`F5` to start debugging. .. figure:: img/vs_4_debugging_main.png diff --git a/development/cpp/configuring_an_ide/visual_studio_code.rst b/development/cpp/configuring_an_ide/visual_studio_code.rst index 8402aab..69ce5d8 100644 --- a/development/cpp/configuring_an_ide/visual_studio_code.rst +++ b/development/cpp/configuring_an_ide/visual_studio_code.rst @@ -13,7 +13,7 @@ Importing the project the `official documentation `_. Alternatively, `clangd `_ can be used instead. -- When using the clangd extension, run ``scons compiledb=yes``. +- When using the clangd extension, run `scons compiledb=yes`. - From the Visual Studio Code's main screen open the Godot root folder with **File > Open Folder...**. - Press :kbd:`Ctrl + Shift + P` to open the command prompt window and enter *Configure Task*. @@ -31,7 +31,7 @@ Importing the project .. figure:: img/vscode_create_tasksjson_others.png :align: center -- Within the ``tasks.json`` file find the ``"tasks"`` array and add a new section to it: +- Within the `tasks.json` file find the `"tasks"` array and add a new section to it: js Linux/X11 @@ -70,7 +70,7 @@ js Windows :figclass: figure-w480 :align: center - An example of a filled out ``tasks.json``. + An example of a filled out `tasks.json`. Arguments can be different based on your own setup and needs. See `doc_introduction_to_the_buildsystem` for a full list of arguments. @@ -78,17 +78,17 @@ Arguments can be different based on your own setup and needs. See Debugging the project --------------------- -To run and debug the project you need to create a new configuration in the ``launch.json`` file. +To run and debug the project you need to create a new configuration in the `launch.json` file. - Press :kbd:`Ctrl + Shift + D` to open the Run panel. -- If ``launch.json`` file is missing you will be prompted to create a new one. +- If `launch.json` file is missing you will be prompted to create a new one. .. figure:: img/vscode_1_create_launch.json.png :align: center - Select **C++ (GDB/LLDB)**. There may be another platform specific option here. If selected, adjust the configuration example provided accordingly. -- Within the ``launch.json`` file find the ``"configurations"`` array and add a new section to it: +- Within the `launch.json` file find the `"configurations"` array and add a new section to it: js X11 @@ -163,7 +163,7 @@ js Windows :figclass: figure-w480 :align: center - An example of a filled out ``launch.json``. + An example of a filled out `launch.json`. .. note:: @@ -176,8 +176,8 @@ js Windows Do note that lldb may work better with llvm-based builds. See `doc_compiling_for_x11` for further information. -The name under ``program`` depends on your build configuration, -e.g. ``godot.x11.tools.64`` for 64-bit X11 platform with ``tools`` enabled. +The name under `program` depends on your build configuration, +e.g. `godot.x11.tools.64` for 64-bit X11 platform with `tools` enabled. If you run into any issues, ask for help in one of `Godot's community channels `__. diff --git a/development/cpp/configuring_an_ide/xcode.rst b/development/cpp/configuring_an_ide/xcode.rst index d27333f..647f8ec 100644 --- a/development/cpp/configuring_an_ide/xcode.rst +++ b/development/cpp/configuring_an_ide/xcode.rst @@ -43,12 +43,12 @@ 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 - include subdirectories as well. To achieve that, add two two asterisks (``**``) to the - end of the path, e.g. ``/Users/me/repos/godot-source/**``. + include subdirectories as well. To achieve that, add two two asterisks (`**`) to the + end of the path, e.g. `/Users/me/repos/godot-source/**`. - Add the Godot source to the project by dragging and dropping it into the project file browser. - Uncheck **Create external build system project**. @@ -99,11 +99,11 @@ To enable debugging support you need to edit the external build target's build a - Set the **Executable** to the file you linked in your post-build action script. - Check **Debug executable**. - You can add two arguments on the **Arguments** tab: - the ``-e`` flag opens the editor instead of the project manager, and the ``--path`` argument + the `-e` flag opens the editor instead of the project manager, and the `--path` argument tells the executable to open the specified project (must be provided as an *absolute* path - to the project root, not the ``project.godot`` file). + to the project root, not the `project.godot` file). -To check that everything is working, put a breakpoint in ``platform/osx/godot_main_osx.mm`` and +To check that everything is working, put a breakpoint in `platform/osx/godot_main_osx.mm` and run the project. If you run into any issues, ask for help in one of diff --git a/development/cpp/core_types.rst b/development/cpp/core_types.rst index 94238cb..68bdeec 100644 --- a/development/cpp/core_types.rst +++ b/development/cpp/core_types.rst @@ -12,18 +12,18 @@ understanding. Definitions ----------- -Godot uses the standard C99 datatypes, such as ``uint8_t``, -``uint32_t``, ``int64_t``, etc. which are nowadays supported by every +Godot uses the standard C99 datatypes, such as `uint8_t`, +`uint32_t`, `int64_t`, etc. which are nowadays supported by every compiler. Reinventing the wheel for those is not fun, as it makes code more difficult to read. In general, care is not taken to use the most efficient datatype for a -given task unless using large structures or arrays. ``int`` is used +given task unless using large structures or arrays. `int` is used through most of the code unless necessary. This is done because nowadays every device has at least a 32 bits bus and can do such operations in one cycle. It makes code more readable too. -For files or memory sizes, ``size_t`` is used, which is warranted to be +For files or memory sizes, `size_t` is used, which is warranted to be 64 bits. For Unicode characters, CharType instead of wchar_t is used, because diff --git a/development/cpp/custom_audiostreams.rst b/development/cpp/custom_audiostreams.rst index 878f1c7..89e3b97 100644 --- a/development/cpp/custom_audiostreams.rst +++ b/development/cpp/custom_audiostreams.rst @@ -42,7 +42,7 @@ internal/external buffer, or a file reference. Some AudioStreams need to be stateless such as objects loaded from ResourceLoader. ResourceLoader loads once and references the same -object regardless how many times ``load`` is called on a specific resource. +object regardless how many times `load` is called on a specific resource. Therefore, playback state must be self-contained in AudioStreamPlayback. .. code-block:: cpp @@ -122,7 +122,7 @@ References: Create an AudioStreamPlayback ----------------------------- -AudioStreamPlayer uses ``mix`` callback to obtain PCM data. The callback must match sample rate and fill the buffer. +AudioStreamPlayer uses `mix` callback to obtain PCM data. The callback must match sample rate and fill the buffer. Since AudioStreamPlayback is controlled by the audio thread, i/o and dynamic memory allocation are forbidden. @@ -235,8 +235,8 @@ Godot's AudioServer currently uses 44100 Hz sample rate. When other sample rates needed such as 48000, either provide one or use AudioStreamPlaybackResampled. Godot provides cubic interpolation for audio resampling. -Instead of overloading ``mix``, AudioStreamPlaybackResampled uses ``_mix_internal`` to -query AudioFrames and ``get_stream_sampling_rate`` to query current mix rate. +Instead of overloading `mix`, AudioStreamPlaybackResampled uses `_mix_internal` to +query AudioFrames and `get_stream_sampling_rate` to query current mix rate. .. code-block:: cpp diff --git a/development/cpp/custom_godot_servers.rst b/development/cpp/custom_godot_servers.rst index eac6161..52c7e71 100644 --- a/development/cpp/custom_godot_servers.rst +++ b/development/cpp/custom_godot_servers.rst @@ -273,8 +273,8 @@ an initialization state and a cleanup procedure. Custom managed resource data ---------------------------- -Godot servers implement a mediator pattern. All data types inherit ``RID_Data``. -``RID_Owner`` owns the object when ``make_rid`` is called. During debug mode only, +Godot servers implement a mediator pattern. All data types inherit `RID_Data`. +`RID_Owner` owns the object when `make_rid` is called. During debug mode only, RID_Owner maintains a list of RIDs. In practice, RIDs are similar to writing object-oriented C code. @@ -321,15 +321,15 @@ References Registering the class in GDScript --------------------------------- -Servers are allocated in ``register_types.cpp``. The constructor sets the static -instance and ``init()`` creates the managed thread; ``unregister_types.cpp`` +Servers are allocated in `register_types.cpp`. The constructor sets the static +instance and `init()` creates the managed thread; `unregister_types.cpp` cleans up the server. Since a Godot server class creates an instance and binds it to a static singleton, binding the class might not reference the correct instance. Therefore, a dummy class must be created to reference the proper Godot server. -In ``register_server_types()``, ``Engine::get_singleton()->add_singleton`` +In `register_server_types()`, `Engine::get_singleton()->add_singleton` is used to register the dummy class in GDScript. .. code-block:: cpp @@ -467,9 +467,9 @@ MessageQueue In order to send commands into SceneTree, MessageQueue is a thread-safe buffer to queue set and call methods for other threads. To queue a command, obtain -the target object RID and use either ``push_call``, ``push_set``, or ``push_notification`` +the target object RID and use either `push_call`, `push_set`, or `push_notification` to execute the desired behavior. The queue will be flushed whenever either -``SceneTree::idle`` or ``SceneTree::iteration`` is executed. +`SceneTree::idle` or `SceneTree::iteration` is executed. References: ~~~~~~~~~~~ diff --git a/development/cpp/custom_modules_in_cpp.rst b/development/cpp/custom_modules_in_cpp.rst index c4d4e09..80971f2 100644 --- a/development/cpp/custom_modules_in_cpp.rst +++ b/development/cpp/custom_modules_in_cpp.rst @@ -11,7 +11,7 @@ created and then enabled/disabled. This allows for adding new engine functionality at every level without modifying the core, which can be split for use and reuse in different modules. -Modules are located in the ``modules/`` subdirectory of the build system. +Modules are located in the `modules/` subdirectory of the build system. By default, dozens of modules are enabled, such as GDScript (which, yes, is not part of the base engine), the Mono runtime, a regular expressions module, and others. As many new modules as desired can be @@ -38,10 +38,10 @@ Before creating a module, make sure to `download the source code of Godot and compile it `. To create a new module, the first step is creating a directory inside -``modules/``. If you want to maintain the module separately, you can checkout +`modules/`. If you want to maintain the module separately, you can checkout a different VCS into modules and use it. -The example module will be called "summator" (``godot/modules/summator``). +The example module will be called "summator" (`godot/modules/summator`). Inside we will create a simple summator class: .. code-block:: cpp @@ -111,7 +111,7 @@ need to be created: .. important:: These files must be in the top-level folder of your module (next to your - ``SCsub`` and ``config.py`` files) for the module to be registered properly. + `SCsub` and `config.py` files) for the module to be registered properly. These files should contain the following: @@ -140,7 +140,7 @@ These files should contain the following: // Nothing to do here in this example. } -Next, we need to create a ``SCsub`` file so the build system compiles +Next, we need to create a `SCsub` file so the build system compiles this module: .. code-block:: python @@ -172,8 +172,8 @@ environment's paths: env.Append(CPPPATH=["#myotherlib/include"]) # this is an 'absolute' path If you want to add custom compiler flags when building your module, you need to clone -``env`` first, so it won't add those flags to whole Godot build (which can cause errors). -Example ``SCsub`` with custom flags: +`env` first, so it won't add those flags to whole Godot build (which can cause errors). +Example `SCsub` with custom flags: .. code-block:: python @@ -190,7 +190,7 @@ Example ``SCsub`` with custom flags: # - Append CXXFLAGS for C++ code only. And finally, the configuration file for the module, this is a simple -python script that must be named ``config.py``: +python script that must be named `config.py`: .. code-block:: python @@ -203,7 +203,7 @@ python script that must be named ``config.py``: pass The module is asked if it's OK to build for the specific platform (in -this case, ``True`` means it will build for every platform). +this case, `True` means it will build for every platform). And that's it. Hope it was not too complex! Your module should look like this: @@ -223,7 +223,7 @@ your module will be included. .. 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``. + file `core/method_bind_ext.gen.inc`. Using the module ---------------- @@ -239,7 +239,7 @@ You can now use your newly created module from any script: s.reset() ``` -The output will be ``60``. +The output will be `60`. .. seealso:: The previous Summator example is great for small, custom modules, but what if you want to use a larger, external library? Refer to @@ -258,20 +258,20 @@ Compiling a module externally ----------------------------- Compiling a module involves moving the module's sources directly under the -engine's ``modules/`` directory. While this is the most straightforward way to +engine's `modules/` directory. While this is the most straightforward way to compile a module, there are a couple of reasons as to why this might not be a practical thing to do: 1. Having to manually copy modules sources every time you want to compile the engine with or without the module, or taking additional steps needed to manually disable a module during compilation with a build option similar to - ``module_summator_enabled=no``. Creating symbolic links may also be a solution, + `module_summator_enabled=no`. Creating symbolic links may also be a solution, but you may additionally need to overcome OS restrictions like needing the symbolic link privilege if doing this via script. 2. Depending on whether you have to work with the engine's source code, the - module files added directly to ``modules/`` changes the working tree to the - point where using a VCS (like ``git``) proves to be cumbersome as you need to + module files added directly to `modules/` changes the working tree to the + point where using a VCS (like `git`) proves to be cumbersome as you need to make sure that only the engine-related code is committed by filtering changes. @@ -283,7 +283,7 @@ take our "summator" module and move it to the engine's parent directory: mkdir ../modules mv modules/summator ../modules -Compile the engine with our module by providing ``custom_modules`` build option +Compile the engine with our module by providing `custom_modules` build option which accepts a comma-separated list of directory paths containing custom C++ modules, similar to the following: @@ -291,12 +291,12 @@ modules, similar to the following: scons custom_modules=../modules -The build system shall detect all modules under the ``../modules`` directory +The build system shall detect all modules under the `../modules` directory and compile them accordingly, including our "summator" module. .. warning:: - Any path passed to ``custom_modules`` will be converted to an absolute path + 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. @@ -365,10 +365,10 @@ library that will be dynamically loaded when starting our game's binary. shared_lib_shim = shared_lib[0].name.rsplit('.', 1)[0] env.Append(LIBS=[shared_lib_shim]) -Once compiled, we should end up with a ``bin`` directory containing both the -``godot*`` binary and our ``libsummator*.so``. However given the .so is not in -a standard directory (like ``/usr/lib``), we have to help our binary find it -during runtime with the ``LD_LIBRARY_PATH`` environment variable: +Once compiled, we should end up with a `bin` directory containing both the +`godot*` binary and our `libsummator*.so`. However given the .so is not in +a standard directory (like `/usr/lib`), we have to help our binary find it +during runtime with the `LD_LIBRARY_PATH` environment variable: .. code-block:: shell @@ -376,13 +376,13 @@ during runtime with the ``LD_LIBRARY_PATH`` environment variable: ./bin/godot* .. note:: - You have to ``export`` the environment variable. Otherwise, + You have to `export` the environment variable. Otherwise, you won't be able to run your project from the editor. On top of that, it would be nice to be able to select whether to compile our module as shared library (for development) or as a part of the Godot binary (for release). To do that we can define a custom flag to be passed to SCons -using the ``ARGUMENT`` command: +using the `ARGUMENT` command: .. code-block:: python @@ -410,8 +410,8 @@ using the ``ARGUMENT`` command: # Static compilation module_env.add_source_files(env.modules_sources, sources) -Now by default ``scons`` command will build our module as part of Godot's binary -and as a shared library when passing ``summator_shared=yes``. +Now by default `scons` command will build our module as part of Godot's binary +and as a shared library when passing `summator_shared=yes`. Finally, you can even speed up the build further by explicitly specifying your shared module as target in the SCons command: @@ -432,9 +432,9 @@ kind to your future self! There are several steps in order to setup custom docs for the module: 1. Make a new directory in the root of the module. The directory name can be - anything, but we'll be using the ``doc_classes`` name throughout this section. + anything, but we'll be using the `doc_classes` name throughout this section. -2. Now, we need to edit ``config.py``, add the following snippet: +2. Now, we need to edit `config.py`, add the following snippet: .. code-block:: python @@ -446,21 +446,21 @@ There are several steps in order to setup custom docs for the module: "Summator", ] -The ``get_doc_path()`` function is used by the build system to determine +The `get_doc_path()` function is used by the build system to determine the location of the docs. In this case, they will be located in the -``modules/summator/doc_classes`` directory. If you don't define this, -the doc path for your module will fall back to the main ``doc/classes`` +`modules/summator/doc_classes` directory. If you don't define this, +the doc path for your module will fall back to the main `doc/classes` directory. -The ``get_doc_classes()`` method is necessary for the build system to +The `get_doc_classes()` method is necessary for the build system to know which registered classes belong to the module. You need to list all of your classes here. The classes that you don't list will end up in the -main ``doc/classes`` directory. +main `doc/classes` directory. .. tip:: You can use Git to check if you have missed some of your classes by checking the - untracked files with ``git status``. For example:: + untracked files with `git status`. For example:: user@host:~/godot$ git status @@ -478,8 +478,8 @@ main ``doc/classes`` directory. 3. Now we can generate the documentation: -We can do this via running Godot's doctool i.e. ``godot --doctool ``, -which will dump the engine API reference to the given ```` in XML format. +We can do this via running Godot's doctool i.e. `godot --doctool `, +which will dump the engine API reference to the given `` in XML format. In our case we'll point it to the root of the cloned repository. You can point it to an another folder, and just copy over the files that you need. @@ -490,9 +490,9 @@ Run command: user@host:~/godot/bin$ ./bin/ --doctool . -Now if you go to the ``godot/modules/summator/doc_classes`` folder, you will see -that it contains a ``Summator.xml`` file, or any other classes, that you referenced -in your ``get_doc_classes`` function. +Now if you go to the `godot/modules/summator/doc_classes` folder, you will see +that it contains a `Summator.xml` file, or any other classes, that you referenced +in your `get_doc_classes` function. Edit the file(s) following `doc_updating_the_class_reference` and recompile the engine. @@ -507,7 +507,7 @@ the things that you previously added. Of course if you point it to your godot folder, make sure you don't lose work by extracting older docs from an older engine build on top of the newer ones. -Note that if you don't have write access rights to your supplied ````, +Note that if you don't have write access rights to your supplied ``, you might encounter an error similar to the following: .. code-block:: console @@ -529,16 +529,16 @@ please refer to `doc_editor_icons` first. Once you've created your icon(s), proceed with the following steps: -1. Make a new directory in the root of the module named ``icons``. This is the +1. Make a new directory in the root of the module named `icons`. This is the default path for the engine to look for module's editor icons. -2. Move your newly created ``svg`` icons (optimized or not) into that folder. +2. Move your newly created `svg` icons (optimized or not) into that folder. 3. Recompile the engine and run the editor. Now the icon(s) will appear in editor's interface where appropriate. If you'd like to store your icons somewhere else within your module, -add the following code snippet to ``config.py`` to override the default path: +add the following code snippet to `config.py` to override the default path: .. code-block:: python @@ -550,8 +550,8 @@ Summing up Remember to: -- use ``GDCLASS`` macro for inheritance, so Godot can wrap it -- use ``_bind_methods`` to bind your functions to scripting, and to +- use `GDCLASS` macro for inheritance, so Godot can wrap it +- use `_bind_methods` to bind your functions to scripting, and to allow them to work as callbacks for signals. But this is not all, depending what you do, you will be greeted with diff --git a/development/cpp/custom_resource_format_loaders.rst b/development/cpp/custom_resource_format_loaders.rst index 73a8776..5a22bef 100644 --- a/development/cpp/custom_resource_format_loaders.rst +++ b/development/cpp/custom_resource_format_loaders.rst @@ -44,14 +44,14 @@ References Creating a ResourceFormatLoader ------------------------------- -Each file format consist of a data container and a ``ResourceFormatLoader``. +Each file format consist of a data container and a `ResourceFormatLoader`. ResourceFormatLoaders are usually simple classes which return all the necessary metadata for supporting new extensions in Godot. The class must return the format name and the extension string. In addition, ResourceFormatLoaders must convert file paths into -resources with the ``load`` function. To load a resource, ``load`` must +resources with the `load` function. To load a resource, `load` must read and handle data serialization. @@ -109,7 +109,7 @@ Creating a ResourceFormatSaver ------------------------------ If you'd like to be able to edit and save a resource, you can implement a -``ResourceFormatSaver``: +`ResourceFormatSaver`: .. code-block:: cpp @@ -264,8 +264,8 @@ Considerations Some libraries may not define certain common routines such as IO handling. Therefore, Godot call translations are required. -For example, here is the code for translating ``FileAccess`` -calls into ``std::istream``. +For example, here is the code for translating `FileAccess` +calls into `std::istream`. .. code-block:: cpp @@ -309,9 +309,9 @@ References Registering the new file format ------------------------------- -Godot registers ``ResourcesFormatLoader`` with a ``ResourceLoader`` +Godot registers `ResourcesFormatLoader` with a `ResourceLoader` handler. The handler selects the proper loader automatically -when ``load`` is called. +when `load` is called. .. code-block:: cpp @@ -360,7 +360,7 @@ References Loading it on GDScript ---------------------- -Save a file called ``demo.json`` with the following contents and place it in the +Save a file called `demo.json` with the following contents and place it in the project's root folder: .. code-block:: json diff --git a/development/cpp/introduction_to_godot_development.rst b/development/cpp/introduction_to_godot_development.rst index fc3c7da..1147389 100644 --- a/development/cpp/introduction_to_godot_development.rst +++ b/development/cpp/introduction_to_godot_development.rst @@ -23,7 +23,7 @@ If you are writing or correcting bugs affecting Godot Engine's editor, remember that the binary will by default run the project manager first, and then only run the editor in another process once you've selected a project. To launch a project directly, you need to run the editor by -passing the ``-e`` argument to Godot Engine's binary from within your +passing the `-e` argument to Godot Engine's binary from within your project's folder. Typically: .. code-block:: none diff --git a/development/cpp/macos_debug.rst b/development/cpp/macos_debug.rst index fa254ba..d604966 100644 --- a/development/cpp/macos_debug.rst +++ b/development/cpp/macos_debug.rst @@ -7,7 +7,7 @@ Debugging Godot editor Attaching a debugger to the signed macOS process requires the "com.apple.security.get-task-allow" entitlement, which is not enabled by default, since apps can't be notarized as long as it is enabled. If you want to debug an official build of the editor it should be re-signed with the proper entitlements. -Create an ``editor.entitlements`` text file with the following contents: +Create an `editor.entitlements` text file with the following contents: .. code-block:: xml @@ -39,4 +39,4 @@ Then use the following command to re-sign the editor:: Debugging exported project -------------------------- -To allow debugging, select the ``codesign\debugging`` (``com.apple.security.get-task-allow``) entitlement during the export. When it is selected, notarization is not supported and should be disabled. +To allow debugging, select the `codesign\debugging` (`com.apple.security.get-task-allow`) entitlement during the export. When it is selected, notarization is not supported and should be disabled. diff --git a/development/cpp/object_class.rst b/development/cpp/object_class.rst index 2a12441..15a56b1 100644 --- a/development/cpp/object_class.rst +++ b/development/cpp/object_class.rst @@ -60,13 +60,13 @@ Registering as virtual is the same but it can't be instanced. ClassDB::register_virtual_class() Object-derived classes can override the static function -``static void _bind_methods()``. When one class is registered, this +`static void _bind_methods()`. When one class is registered, this static function is called to register all the object methods, properties, constants, etc. It's only called once. If an Object derived class is instanced but has not been registered, it will be registered as virtual automatically. -Inside ``_bind_methods``, there are a couple of things that can be done. +Inside `_bind_methods`, there are a couple of things that can be done. Registering functions is one: .. code-block:: cpp @@ -79,15 +79,15 @@ Default values for arguments can be passed in reverse order: ClassDB::bind_method(D_METHOD("methodname", "arg1name", "arg2name"), &MyCustomType::method, DEFVAL(-1)); // default value for arg2name -``D_METHOD`` is a macro that converts "methodname" to a StringName for more +`D_METHOD` is a macro that converts "methodname" to a StringName for more efficiency. Argument names are used for introspection, but when compiling on release, the macro ignores them, so the strings are unused and optimized away. -Check ``_bind_methods`` of Control or Object for more examples. +Check `_bind_methods` of Control or Object for more examples. If just adding modules and functionality that is not expected to be -documented as thoroughly, the ``D_METHOD()`` macro can safely be ignored and a +documented as thoroughly, the `D_METHOD()` macro can safely be ignored and a string passing the name can be passed for brevity. References: @@ -114,7 +114,7 @@ convertible to int, for this a macro is provided: VARIANT_ENUM_CAST(MyClass::SomeMode); // now functions that take SomeMode can be bound. -The constants can also be bound inside ``_bind_methods``, by using: +The constants can also be bound inside `_bind_methods`, by using: .. code-block:: cpp @@ -165,7 +165,7 @@ functions is preferred for legibility. Many properties are also bound with categories, such as "animation/frame" which also make indexing impossible unless using operator []. -From ``_bind_methods()``, properties can be created and bound as long as +From `_bind_methods()`, properties can be created and bound as long as set/get functions exist. Example: .. code-block:: cpp @@ -176,7 +176,7 @@ This creates the property using the setter and the getter. .. _doc_binding_properties_using_set_get_property_list: -Binding properties using ``_set``/``_get``/``_get_property_list`` +Binding properties using `_set`/`_get`/`_get_property_list` ----------------------------------------------------------------- An additional method of creating properties exists when more flexibility @@ -194,7 +194,7 @@ call). bool _get(const StringName &p_property, Variant &r_value) const; // return true if property was found bool _set(const StringName &p_property, const Variant &p_value); // return true if property was found -This is also a little less efficient since ``p_property`` must be +This is also a little less efficient since `p_property` must be compared against the desired names in serial order. Dynamic casting @@ -227,11 +227,11 @@ languages). Connecting to them is rather easy: // for example: obj->connect("enter_tree", this, "_node_entered_tree") -The method ``_node_entered_tree`` must be registered to the class using -``ClassDB::bind_method`` (explained before). +The method `_node_entered_tree` must be registered to the class using +`ClassDB::bind_method` (explained before). -Adding signals to a class is done in ``_bind_methods``, using the -``ADD_SIGNAL`` macro, for example: +Adding signals to a class is done in `_bind_methods`, using the +`ADD_SIGNAL` macro, for example: .. code-block:: cpp @@ -259,7 +259,7 @@ Declaring them must be done using Ref<> template. For example: Ref myref(memnew(MyReference)); -``myref`` is reference counted. It will be freed when no more Ref<> +`myref` is reference counted. It will be freed when no more Ref<> templates point to it. References: @@ -272,7 +272,7 @@ Resources: `Resource` inherits from Reference, so all resources are reference counted. Resources can optionally contain a path, which -reference a file on disk. This can be set with ``resource.set_path(path)``. +reference a file on disk. This can be set with `resource.set_path(path)`. This is normally done by the resource loader though. No two different resources can have the same path, attempt to do so will result in an error. @@ -316,7 +316,7 @@ Saving a resource can be done with the resource saver API: Instance will be saved. Sub resources that have a path to a file will be saved as a reference to that resource. Sub resources without a path will be bundled with the saved resource and assigned sub-IDs, like -``res://someresource.res::1``. This also helps to cache them when loaded. +`res://someresource.res::1`. This also helps to cache them when loaded. References: ~~~~~~~~~~~ diff --git a/development/cpp/using_cpp_profilers.rst b/development/cpp/using_cpp_profilers.rst index 0f52ecc..a600943 100644 --- a/development/cpp/using_cpp_profilers.rst +++ b/development/cpp/using_cpp_profilers.rst @@ -32,17 +32,17 @@ symbols, since these would make the download size significantly larger. To get profiling data that best matches the production environment, you should compile binaries with the following SCons options: -- For editor binaries: ``target=release_debug use_lto=yes`` -- For debug export templates: ``target=release_debug use_lto=yes`` -- For release export templates: ``tools=no target=release debug_symbols=yes`` - - ``debug_symbols=yes`` is required as export templates are stripped from debugging symbols by default. +- For editor binaries: `target=release_debug use_lto=yes` +- For debug export templates: `target=release_debug use_lto=yes` +- For release export templates: `tools=no target=release debug_symbols=yes` + - `debug_symbols=yes` is required as export templates are stripped from debugging symbols by default. -It is possible to run a profiler on less optimized builds (e.g. ``target=debug`` without LTO), +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:: - Do *not* strip debugging symbols on the binaries using the ``strip`` command + Do *not* strip debugging symbols on the binaries using the `strip` command after compiling the binaries. Otherwise, you will no longer get useful profiling information when running a profiler. @@ -50,10 +50,10 @@ Benchmarking startup/shutdown times ----------------------------------- If you're looking into optimizing Godot's startup/shutdown performance, -you can tell the profiler to use the ``--quit`` command line option on the Godot binary. +you can tell the profiler to use the `--quit` command line option on the Godot binary. This will exit Godot just after it finished starting. -The ``--quit`` option works with ``--editor``, ``--project-manager`` or -``--path `` (which runs a project directly). +The `--quit` option works with `--editor`, `--project-manager` or +`--path ` (which runs a project directly). .. seealso:: @@ -95,7 +95,7 @@ HotSpot - In the next window, specify the path to the Godot binary that includes debug symbols. - Specify command line arguments to run a specific project, with or without the editor. - The path to the working directory can be anything if an absolute path is used - for the ``--path`` command line argument. Otherwise, it must be set to that + for the `--path` command line argument. Otherwise, it must be set to that the relative path to the project is valid. - Make sure **Elevate Privileges** is checked if you have administrative privileges. While not essential for profiling Godot, this will ensure all events can be captured. diff --git a/development/editor/creating_icons.rst b/development/editor/creating_icons.rst index c1d57d8..3dfe0a5 100644 --- a/development/editor/creating_icons.rst +++ b/development/editor/creating_icons.rst @@ -14,7 +14,7 @@ Creating icons To create new icons, you first need a vector graphics editor installed. For instance, you can use the open source `Inkscape `_ editor. -Clone the ``godot`` repository containing all the editor icons: +Clone the `godot` repository containing all the editor icons: .. code-block:: bash @@ -29,9 +29,9 @@ two main requirements to follow: You can create a 16×16 grid in Inkscape to make this easier. Once you're satisfied with the icon's design, save the icon in the cloned -repository's ``editor/icons`` folder. The icon name should match the intended +repository's `editor/icons` folder. The icon name should match the intended name in a case-sensitive manner. For example, to create an icon for -CPUParticles2D, name the file ``CPUParticles2D.svg``. +CPUParticles2D, name the file `CPUParticles2D.svg`. Color conversion for light editor themes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -53,17 +53,17 @@ optimized before being added to the engine, to do so: 1. Install `svgcleaner `__ by downloading a binary from its `Releases tab `__ - and placing it into a location in your ``PATH`` environment variable. + and placing it into a location in your `PATH` environment variable. -2. Run the command below, replacing ``svg_source.svg`` with the path to your +2. Run the command below, replacing `svg_source.svg` with the path to your SVG file (which can be a relative or absolute path): .. code-block:: bash svgcleaner --multipass svg_source.svg svg_optimized.svg -The ``--multipass`` switch improves compression, so make sure to include it. -The optimized icon will be saved to ``svg_optimized.svg``. You can also change +The `--multipass` switch improves compression, so make sure to include it. +The optimized icon will be saved to `svg_optimized.svg`. You can also change the destination parameter to any relative or absolute path you'd like. .. note:: @@ -77,7 +77,7 @@ Integrating and sharing the icons ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you're contributing to the engine itself, you should make a pull request to -add optimized icons to ``editor/icons`` in the main repository. Recompile the +add optimized icons to `editor/icons` in the main repository. Recompile the engine to make it pick up new icons for classes. It's also possible to create custom icons within a module. If you're creating @@ -95,7 +95,7 @@ If icons don't appear in the editor, make sure that: 1. Each icon's filename matches the naming requirement as described previously. -2. ``modules/svg`` is enabled (it should be enabled by default). Without it, +2. `modules/svg` is enabled (it should be enabled by default). Without it, icons won't appear in the editor at all. References diff --git a/development/editor/editor_style_guide.rst b/development/editor/editor_style_guide.rst index ed0bd5f..fd34245 100644 --- a/development/editor/editor_style_guide.rst +++ b/development/editor/editor_style_guide.rst @@ -22,7 +22,7 @@ Writing style - **Use contractions.** For example, use "isn't" instead of "is not". An exception to this rule can be made when you specifically want to emphasize one of the contraction's words. -- **Use double quotes in messages** (``""``) instead of single quotes (``''``). +- **Use double quotes in messages** (`""`) instead of single quotes (`''`). Double quotes should be used to quote user input, file paths and possibly other things depending on the context. @@ -39,7 +39,7 @@ Capitalize text in buttons and menu actions: - **Good:** *Open Editor Data Folder* - **Bad:** *Open editor data folder* -If a menu action opens a modal dialog, suffix it with an ellipsis (``...``). +If a menu action opens a modal dialog, suffix it with an ellipsis (`...`). - **Good:** *Editor Settings...* - **Bad:** *Editor Settings* @@ -87,9 +87,9 @@ Consider adding tooltips whenever the action performed by a button or menu action isn't obvious. You can also provide additional context or highlight caveats in the tooltip. -You can do this by calling ``set_tooltip(TTR("Text here."))`` on the +You can do this by calling `set_tooltip(TTR("Text here."))` on the Control-based node in question. If the tooltip is particularly long (more than -~80 characters), wrap it over several lines by adding line breaks using ``\n``. +~80 characters), wrap it over several lines by adding line breaks using `\n`. Tooltips should follow the writing style described above. In addition to this, use indicative mood instead of imperative mood: diff --git a/development/editor/introduction_to_editor_development.rst b/development/editor/introduction_to_editor_development.rst index 75b637e..16d7020 100644 --- a/development/editor/introduction_to_editor_development.rst +++ b/development/editor/introduction_to_editor_development.rst @@ -56,26 +56,26 @@ Some important files in the editor are: Where the 3D editor gizmos are defined and drawn. This file doesn't have a 2D counterpart as 2D gizmos are drawn by the nodes themselves. -Editor dependencies in ``scene/`` files +Editor dependencies in `scene/` files --------------------------------------- When working on an editor feature, you may have to modify files in -Godot's GUI nodes, which you can find in the ``scene/`` folder. +Godot's GUI nodes, which you can find in the `scene/` folder. One rule to keep in mind is that you must **not** introduce new dependencies to -``editor/`` includes in other folders such as ``scene/``. This applies even if -you use ``#ifdef TOOLS_ENABLED``. +`editor/` includes in other folders such as `scene/`. This applies even if +you use `#ifdef TOOLS_ENABLED`. To make the codebase easier to follow and more self-contained, the allowed dependency order is: -- ``editor/`` -> ``scene/`` -> ``servers/`` -> ``core/`` +- `editor/` -> `scene/` -> `servers/` -> `core/` -This means that files in ``editor/`` can depend on includes from ``scene/``, -``servers/``, and ``core/``. But, for example, while ``scene/`` can depend on includes -from ``servers/`` and ``core/``, it cannot depend on includes from ``editor/``. +This means that files in `editor/` can depend on includes from `scene/`, +`servers/`, and `core/`. But, for example, while `scene/` can depend on includes +from `servers/` and `core/`, it cannot depend on includes from `editor/`. -Currently, there are some dependencies to ``editor/`` includes in ``scene/`` +Currently, there are some dependencies to `editor/` includes in `scene/` files, but `they are in the process of being removed `__. diff --git a/development/file_formats/tscn.rst b/development/file_formats/tscn.rst index d2912bf..b0905d2 100644 --- a/development/file_formats/tscn.rst +++ b/development/file_formats/tscn.rst @@ -11,13 +11,13 @@ The ESCN (exported scene) file format is identical to the TSCN file format, but is used to indicate to Godot that the file has been exported from another program and should not be edited by the user from within Godot. Unlike SCN and TSCN files, during import, ESCN files are compiled to binary -SCN files stored inside the ``.import/`` folder. +SCN files stored inside the `.import/` folder. This reduces the data size and speeds up loading, as binary formats are faster to load compared to text-based formats. For those looking for a complete description, the parsing is handled in the file `resource_format_text.cpp `_ -in the ``ResourceFormatLoaderText`` class. +in the `ResourceFormatLoaderText` class. File structure -------------- @@ -30,34 +30,34 @@ There are five main sections inside the TSCN file: 3. Nodes 4. Connections -The file descriptor looks like ``[gd_scene load_steps=3 format=2]`` and should -be the first entry in the file. The ``load_steps`` parameter is equal to the +The file descriptor looks like `[gd_scene load_steps=3 format=2]` and should +be the first entry in the file. The `load_steps` parameter is equal to the total amount of resources (internal and external) plus one (for the file itself). -If the file has no resources, ``load_steps`` is omitted. The engine will -still load the file correctly if ``load_steps`` is incorrect, but this will affect +If the file has no resources, `load_steps` is omitted. The engine will +still load the file correctly if `load_steps` is incorrect, but this will affect loading bars and any other piece of code relying on that value. These sections should appear in order, but it can be hard to distinguish them. The only difference between them is the first element in the heading for all of the items in the section. For example, the heading of all external resources -should start with ``[ext_resource .....]``. +should start with `[ext_resource .....]`. -A TSCN file may contain single-line comments starting with a semicolon (``;``). +A TSCN file may contain single-line comments starting with a semicolon (`;`). However, comments will be discarded when saving the file using the Godot editor. Entries inside the file ~~~~~~~~~~~~~~~~~~~~~~~ A heading looks like -``[ key=value key=value key=value ...]`` +`[ key=value key=value key=value ...]` where resource_type is one of: -- ``ext_resource`` -- ``sub_resource`` -- ``node`` -- ``connection`` +- `ext_resource` +- `sub_resource` +- `node` +- `connection` -Below every heading comes zero or more ``key = value`` pairs. The +Below every heading comes zero or more `key = value` pairs. The values can be complex datatypes such as Arrays, Transforms, Colors, and so on. For example, a spatial node looks like: @@ -72,22 +72,22 @@ The scene tree The scene tree is made up of… nodes! The heading of each node consists of its name, parent and (most of the time) a type. For example -``[node type="Camera" name="PlayerCamera" parent="Player/Head"]`` +`[node type="Camera" name="PlayerCamera" parent="Player/Head"]` Other valid keywords include: - - ``instance`` - - ``instance_placeholder`` - - ``owner`` - - ``index`` (sets the order of appearance in the tree. If absent, inherited nodes will take precedence over plain ones) - - ``groups`` + - `instance` + - `instance_placeholder` + - `owner` + - `index` (sets the order of appearance in the tree. If absent, inherited nodes will take precedence over plain ones) + - `groups` The first node in the file, which is also the scene root, must not have a -``parent=Path/To/Node`` entry in its heading. All scene files should have +`parent=Path/To/Node` entry in its heading. All scene files should have exactly *one* scene root. If it doesn't, Godot will fail to import the file. The parent path of other nodes should be absolute, but shouldn't contain the scene root's name. If the node is a direct child of the scene root, -the path should be ``"."``. Here is an example scene tree +the path should be `"."`. Here is an example scene tree (but without any node content): :: @@ -140,10 +140,10 @@ NodePath ~~~~~~~~ A tree structure is not enough to represent the whole scene. Godot uses a -``NodePath(Path/To/Node)`` structure to refer to another node or attribute of +`NodePath(Path/To/Node)` structure to refer to another node or attribute of the node anywhere in the scene tree. For instance, MeshInstance uses -``NodePath()`` to point to its skeleton. Likewise, Animation tracks use -``NodePath()`` to point to node properties to animate. +`NodePath()` to point to its skeleton. Likewise, Animation tracks use +`NodePath()` to point to node properties to animate. :: @@ -167,22 +167,22 @@ Skeleton ~~~~~~~~ The Skeleton node inherits the Spatial node, but also may have a list of bones -described in key-value pairs in the format ``bones/Id/Attribute=Value``. The +described in key-value pairs in the format `bones/Id/Attribute=Value`. The bone attributes consist of: -- ``name`` -- ``parent`` -- ``rest`` -- ``pose`` -- ``enabled`` -- ``bound_children`` +- `name` +- `parent` +- `rest` +- `pose` +- `enabled` +- `bound_children` -1. ``name`` must be the first attribute of each bone. -2. ``parent`` is the index of parent bone in the bone list, with parent index, +1. `name` must be the first attribute of each bone. +2. `parent` is the index of parent bone in the bone list, with parent index, the bone list is built to a bone tree. -3. ``rest`` is the transform matrix of bone in its "resting" position. -4. ``pose`` is the pose matrix; use ``rest`` as the basis. -5. ``bound_children`` is a list of ``NodePath()`` which point to +3. `rest` is the transform matrix of bone in its "resting" position. +4. `pose` is the pose matrix; use `rest` as the basis. +5. `bound_children` is a list of `NodePath()` which point to BoneAttachments belonging to this bone. Here's an example of a skeleton node with two bones: @@ -210,8 +210,8 @@ BoneAttachment BoneAttachment node is an intermediate node to describe some node being parented to a single bone in a Skeleton node. The BoneAttachment has a -``bone_name=NameOfBone`` attribute, and the corresponding bone being the parent has the -BoneAttachment node in its ``bound_children`` list. +`bone_name=NameOfBone` attribute, and the corresponding bone being the parent has the +BoneAttachment node in its `bound_children` list. An example of one MeshInstance parented to a bone in Skeleton: @@ -241,10 +241,10 @@ AnimationPlayer ~~~~~~~~~~~~~~~ AnimationPlayer works as an animation library. It stores animations listed in -the format ``anim/Name=SubResource(ResourceId)``; each line refers to an +the format `anim/Name=SubResource(ResourceId)`; each line refers to an Animation resource. All the animation resources use the root node of AnimationPlayer. The root node is stored as -``root_node=NodePath(Path/To/Node)``. +`root_node=NodePath(Path/To/Node)`. :: @@ -266,14 +266,14 @@ Resources are components that make up the nodes. For example, a MeshInstance node will have an accompanying ArrayMesh resource. The ArrayMesh resource may be either internal or external to the TSCN file. -References to the resources are handled by ``id`` numbers in the resource's +References to the resources are handled by `id` numbers in the resource's heading. External resources and internal resources are referred to with -``ExtResource(id)`` and ``SubResource(id)``, respectively. Because there +`ExtResource(id)` and `SubResource(id)`, respectively. Because there have different methods to refer to internal and external resources, you can have the same ID for both an internal and external resource. -For example, to refer to the resource ``[ext_resource id=3 type="PackedScene" -path=....]``, you would use ``ExtResource(3)``. +For example, to refer to the resource `[ext_resource id=3 type="PackedScene" +path=....]`, you would use `ExtResource(3)`. External resources ~~~~~~~~~~~~~~~~~~ @@ -282,7 +282,7 @@ External resources are links to resources not contained within the TSCN file itself. An external resource consists of a path, a type and an ID. Godot always generates absolute paths relative to the resource directory and -thus prefixed with ``res://``, but paths relative to the TSCN file's location +thus prefixed with `res://`, but paths relative to the TSCN file's location are also valid. Some example external resources are: @@ -294,7 +294,7 @@ Some example external resources are: Like TSCN files, a TRES file may contain single-line comments starting with a -semicolon (``;``). However, comments will be discarded when saving the resource +semicolon (`;`). However, comments will be discarded when saving the resource using the Godot editor. Internal resources @@ -303,7 +303,7 @@ Internal resources A TSCN file can contain meshes, materials and other data. These are contained in the *internal resources* section of the file. The heading for an internal resource looks similar to those of external resources, except that it doesn't -have a path. Internal resources also have ``key=value`` pairs under each +have a path. Internal resources also have `key=value` pairs under each heading. For example, a capsule collision shape looks like: :: @@ -326,21 +326,21 @@ others can only be found by looking through Godot's source. ArrayMesh ~~~~~~~~~ -ArrayMesh consists of several surfaces, each in the format ``surface\Index={}``. +ArrayMesh consists of several surfaces, each in the format `surface\Index={}`. Each surface is a set of vertices and a material. TSCN files support two surface formats: 1. For the old format, each surface has three essential keys: -- ``primitive`` -- ``arrays`` -- ``morph_arrays`` +- `primitive` +- `arrays` +- `morph_arrays` - i. ``primitive`` is an enumerate variable, ``primitive=4`` which is - ``PRIMITIVE_TRIANGLES`` is frequently used. + i. `primitive` is an enumerate variable, `primitive=4` which is + `PRIMITIVE_TRIANGLES` is frequently used. - ii. ``arrays`` is a two-dimensional array, it contains: + ii. `arrays` is a two-dimensional array, it contains: 1. Vertex positions array 2. Normals array @@ -352,8 +352,8 @@ TSCN files support two surface formats: 8. Bone weights array 9. Vertex indexes array - iii. ``morph_arrays`` is an array of morphs. Each morph is exactly an - ``arrays`` without the vertex indexes array. + iii. `morph_arrays` is an array of morphs. Each morph is exactly an + `arrays` without the vertex indexes array. An example of ArrayMesh: @@ -381,44 +381,44 @@ An example of ArrayMesh: Animation ~~~~~~~~~ -An animation resource consists of tracks. Besides, it has ``length``, ``loop`` -and ``step`` applied to all the tracks. +An animation resource consists of tracks. Besides, it has `length`, `loop` +and `step` applied to all the tracks. -1. ``length`` and ``step`` are both durations in seconds. +1. `length` and `step` are both durations in seconds. Each track is described by a list of key-value pairs in the format -``tracks/Id/Attribute``. Each track includes: +`tracks/Id/Attribute`. Each track includes: -- ``type`` -- ``path`` -- ``interp`` -- ``keys`` -- ``loop_wrap`` -- ``imported`` -- ``enabled`` +- `type` +- `path` +- `interp` +- `keys` +- `loop_wrap` +- `imported` +- `enabled` -1. The ``type`` must be the first attribute of each track. - The value of ``type`` can be: +1. The `type` must be the first attribute of each track. + The value of `type` can be: - - ``transform`` - - ``value`` - - ``method`` + - `transform` + - `value` + - `method` -2. The ``path`` has the format ``NodePath(Path/To/Node:attribute)``. +2. The `path` has the format `NodePath(Path/To/Node:attribute)`. It's the path to the animated node or attribute, relative to the root node defined in the AnimationPlayer. -3. The ``interp`` is the method to interpolate frames from the keyframes. +3. The `interp` is the method to interpolate frames from the keyframes. It is an enum variable with one of the following values: - - ``0`` (constant) - - ``1`` (linear) - - ``2`` (cubic) + - `0` (constant) + - `1` (linear) + - `2` (cubic) -4. The ``keys`` correspond to the keyframes. It appears as a ``PoolRealArray()``, +4. The `keys` correspond to the keyframes. It appears as a `PoolRealArray()`, but may have a different structure for tracks with different types. - - A Transform track uses every 12 real numbers in the ``keys`` to describe + - A Transform track uses every 12 real numbers in the `keys` to describe a keyframe. The first number is the timestamp. The second number is the transition followed by a 3-number translation vector, followed by a 4-number rotation quaternion (X, Y, Z, W) and finally a 3-number diff --git a/getting_started/first_2d_game/01.project_setup.rst b/getting_started/first_2d_game/01.project_setup.rst index 14dd28d..2a57add 100644 --- a/getting_started/first_2d_game/01.project_setup.rst +++ b/getting_started/first_2d_game/01.project_setup.rst @@ -14,8 +14,8 @@ GDScript ``` Download :download:`dodge_assets.zip `. The archive contains the images and sounds you'll be using - to make the game. Extract the archive and move the ``art/`` - and ``fonts/`` directories to your project's directory. + to make the game. Extract the archive and move the `art/` + and `fonts/` directories to your project's directory. ``` Your project folder should look like this. @@ -25,12 +25,12 @@ Your project folder should look like this. This game is designed for portrait mode, so we need to adjust the size of the game window. Click on *Project -> Project Settings* to open the project settings window and in the left column, open the *Display -> Window* tab. There, set -"Width" to ``480`` and "Height" to ``720``. +"Width" to `480` and "Height" to `720`. .. image:: img/setting-project-width-and-height.png Also, scroll down to the bottom of the section and, under the "Stretch" options, -set ``Mode`` to "2d" and ``Aspect`` to "keep". This ensures that the game scales +set `Mode` to "2d" and `Aspect` to "keep". This ensures that the game scales consistently on different sized screens. .. image:: img/setting-stretch-mode.png @@ -38,12 +38,12 @@ consistently on different sized screens. Organizing the project ~~~~~~~~~~~~~~~~~~~~~~ -In this project, we will make 3 independent scenes: ``Player``, ``Mob``, and -``HUD``, which we will combine into the game's ``Main`` scene. +In this project, we will make 3 independent scenes: `Player`, `Mob`, and +`HUD`, which we will combine into the game's `Main` scene. In a larger project, it might be useful to create folders to hold the various scenes and their scripts, but for this relatively small game, you can save your -scenes and scripts in the project's root folder, identified by ``res://``. You +scenes and scripts in the project's root folder, identified by `res://`. You can see your project folders in the FileSystem dock in the lower left corner: .. image:: img/filesystem_dock.png diff --git a/getting_started/first_2d_game/02.player_scene.rst b/getting_started/first_2d_game/02.player_scene.rst index c010025..fb10f24 100644 --- a/getting_started/first_2d_game/02.player_scene.rst +++ b/getting_started/first_2d_game/02.player_scene.rst @@ -6,7 +6,7 @@ Creating the player scene With the project settings in place, we can start working on the player-controlled character. -The first scene will define the ``Player`` object. One of the benefits of +The first scene will define the `Player` object. One of the benefits of creating a separate Player scene is that we can test it separately, even before we've created other parts of the game. @@ -23,12 +23,12 @@ what the object *is*. Click the "Other Node" button and add an `Area2D Godot will display a warning icon next to the node in the scene tree. You can ignore it for now. We will address it later. -With ``Area2D`` we can detect objects that overlap or run into the player. -Change the node's name to ``Player`` by double-clicking on it. Now that we've +With `Area2D` we can detect objects that overlap or run into the player. +Change the node's name to `Player` by double-clicking on it. Now that we've set the scene's root node, we can add additional nodes to give it more functionality. -Before we add any children to the ``Player`` node, we want to make sure we don't +Before we add any children to the `Player` node, we want to make sure we don't accidentally move or resize them by clicking on them. Select the node and click the icon to the right of the lock; its tooltip says "Makes sure the object's children are not selectable." @@ -53,12 +53,12 @@ or :kbd:`Cmd + S` on macOS. Sprite animation ~~~~~~~~~~~~~~~~ -Click on the ``Player`` node and add an `AnimatedSprite -` node as a child. The ``AnimatedSprite`` will handle the +Click on the `Player` node and add an `AnimatedSprite +` node as a child. The `AnimatedSprite` will handle the appearance and animations for our player. Notice that there is a warning symbol -next to the node. An ``AnimatedSprite`` requires a `SpriteFrames +next to the node. An `AnimatedSprite` requires a `SpriteFrames ` resource, which is a list of the animations it can -display. To create one, find the ``Frames`` property in the Inspector and click +display. To create one, find the `Frames` property in the Inspector and click "[empty]" -> "New SpriteFrames". Click again to open the "SpriteFrames" panel: .. image:: img/spriteframes_panel.png @@ -66,30 +66,30 @@ display. To create one, find the ``Frames`` property in the Inspector and click On the left is a list of animations. Click the "default" one and rename it to "walk". Then click the "New Animation" button to create a second animation named -"up". Find the player images in the "FileSystem" tab - they're in the ``art`` +"up". Find the player images in the "FileSystem" tab - they're in the `art` folder you unzipped earlier. Drag the two images for each animation, named -``playerGrey_up[1/2]`` and ``playerGrey_walk[1/2]``, into the "Animation Frames" +`playerGrey_up[1/2]` and `playerGrey_walk[1/2]`, into the "Animation Frames" side of the panel for the corresponding animation: .. image:: img/spriteframes_panel2.png The player images are a bit too large for the game window, so we need to scale -them down. Click on the ``AnimatedSprite`` node and set the ``Scale`` property -to ``(0.5, 0.5)``. You can find it in the Inspector under the ``Node2D`` +them down. Click on the `AnimatedSprite` node and set the `Scale` property +to `(0.5, 0.5)`. You can find it in the Inspector under the `Node2D` heading. .. image:: img/player_scale.png Finally, add a `CollisionShape2D` as a child of -``Player``. This will determine the player's "hitbox", or the bounds of its -collision area. For this character, a ``CapsuleShape2D`` node gives the best +`Player`. This will determine the player's "hitbox", or the bounds of its +collision area. For this character, a `CapsuleShape2D` node gives the best fit, so next to "Shape" in the Inspector, click "[empty]"" -> "New CapsuleShape2D". Using the two size handles, resize the shape to cover the sprite: .. image:: img/player_coll_shape.png -When you're finished, your ``Player`` scene should look like this: +When you're finished, your `Player` scene should look like this: .. image:: img/player_scene_nodes.png diff --git a/getting_started/first_2d_game/03.coding_the_player.rst b/getting_started/first_2d_game/03.coding_the_player.rst index 34ce9d7..32c803b 100644 --- a/getting_started/first_2d_game/03.coding_the_player.rst +++ b/getting_started/first_2d_game/03.coding_the_player.rst @@ -7,7 +7,7 @@ In this lesson, we'll add player movement, animation, and set it up to detect collisions. To do so, we need to add some functionality that we can't get from a built-in -node, so we'll add a script. Click the ``Player`` node and click the "Attach +node, so we'll add a script. Click the `Player` node and click the "Attach Script" button: .. image:: img/add_script_button.png @@ -34,16 +34,16 @@ gdscript GDScript var screen_size # Size of the game window. ``` -Using the ``export`` keyword on the first variable ``speed`` allows us to set +Using the `export` keyword on the first variable `speed` allows us to set its value in the Inspector. This can be handy for values that you want to be -able to adjust just like a node's built-in properties. Click on the ``Player`` +able to adjust just like a node's built-in properties. Click on the `Player` node and you'll see the property now appears in the "Script Variables" section of the Inspector. Remember, if you change the value here, it will override the value written in the script. .. image:: img/export_variable.png -The ``_ready()`` function is called when a node enters the scene tree, which is +The `_ready()` function is called when a node enters the scene tree, which is a good time to find the size of the game window: ``` @@ -51,8 +51,8 @@ a good time to find the size of the game window: screen_size = get_viewport_rect().size ``` -Now we can use the ``_process()`` function to define what the player will do. -``_process()`` is called every frame, so we'll use it to update elements of our +Now we can use the `_process()` function to define what the player will do. +`_process()` is called every frame, so we'll use it to update elements of our game, which we expect will change often. For the player, we need to do the following: @@ -68,7 +68,7 @@ map the arrow keys to the four directions. Click on *Project -> Project Settings* to open the project settings window and click on the *Input Map* tab at the top. Type "move_right" in the top bar and -click the "Add" button to add the ``move_right`` action. +click the "Add" button to add the `move_right` action. .. image:: img/input-mapping-add-action.png @@ -80,9 +80,9 @@ desired key. Press the right arrow on your keyboard and click "Ok". Repeat these steps to add three more mappings: -1. ``move_left`` mapped to the left arrow key. -2. ``move_up`` mapped to the up arrow key. -3. And ``move_down`` mapped to the down arrow key. +1. `move_left` mapped to the left arrow key. +2. `move_up` mapped to the up arrow key. +3. And `move_down` mapped to the down arrow key. Your input map tab should look like this: @@ -95,8 +95,8 @@ Click the "Close" button to close the project settings. 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. -You can detect whether a key is pressed using ``Input.is_action_pressed()``, -which returns ``true`` if it's pressed or ``false`` if it isn't. +You can detect whether a key is pressed using `Input.is_action_pressed()`, +which returns `true` if it's pressed or `false` if it isn't. gdscript GDScript ``` @@ -118,37 +118,37 @@ gdscript GDScript $AnimatedSprite.stop() ``` -We start by setting the ``velocity`` to ``(0, 0)`` - by default, the player +We start by setting the `velocity` to `(0, 0)` - by default, the player should not be moving. Then we check each input and add/subtract from the -``velocity`` to obtain a total direction. For example, if you hold ``right`` and -``down`` at the same time, the resulting ``velocity`` vector will be ``(1, 1)``. +`velocity` to obtain a total direction. For example, if you hold `right` and +`down` at the same time, the resulting `velocity` vector will be `(1, 1)`. In this case, since we're adding a horizontal and a vertical movement, the player would move *faster* diagonally than if it just moved horizontally. We can prevent that if we *normalize* the velocity, which means we set its -*length* to ``1``, then multiply by the desired speed. This means no more fast +*length* to `1`, then multiply by the desired speed. This means no more fast diagonal movement. .. 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`. It's good to know but won't be necessary for the rest of this tutorial. -We also check whether the player is moving so we can call ``play()`` or -``stop()`` on the AnimatedSprite. +We also check whether the player is moving so we can call `play()` or +`stop()` on the AnimatedSprite. -.. tip:: ``$`` is shorthand for ``get_node()``. So in the code above, - ``$AnimatedSprite.play()`` is the same as - ``get_node("AnimatedSprite").play()``. +.. tip:: `$` is shorthand for `get_node()`. So in the code above, + `$AnimatedSprite.play()` is the same as + `get_node("AnimatedSprite").play()`. - In GDScript, ``$`` returns the node at the relative path from the - current node, or returns ``null`` if the node is not found. Since + In GDScript, `$` returns the node at the relative path from the + current node, or returns `null` if the node is not found. Since AnimatedSprite is a child of the current node, we can use - ``$AnimatedSprite``. + `$AnimatedSprite`. Now that we have a movement direction, we can update the player's position. We -can also use ``clamp()`` to prevent it from leaving the screen. *Clamping* a +can also use `clamp()` to prevent it from leaving the screen. *Clamping* a value means restricting it to a given range. Add the following to the bottom of -the ``_process`` function (make sure it's not indented under the `else`): +the `_process` function (make sure it's not indented under the `else`): gdscript GDScript @@ -168,11 +168,11 @@ the player around the screen in all directions. .. 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`` + `Attempt to call function 'play' in base 'null instance' on a null + instance` this likely means you spelled the name of the AnimatedSprite node - wrong. Node names are case-sensitive and ``$NodeName`` must match + wrong. Node names are case-sensitive and `$NodeName` must match the name you see in the scene tree. Choosing animations @@ -181,9 +181,9 @@ Choosing animations Now that the player can move, we need to change which animation the AnimatedSprite is playing based on its direction. We have the "walk" animation, which shows the player walking to the right. This animation should be flipped -horizontally using the ``flip_h`` property for left movement. We also have the -"up" animation, which should be flipped vertically with ``flip_v`` for downward -movement. Let's place this code at the end of the ``_process()`` function: +horizontally using the `flip_h` property for left movement. We also have the +"up" animation, which should be flipped vertically with `flip_v` for downward +movement. Let's place this code at the end of the `_process()` function: gdscript GDScript @@ -217,11 +217,11 @@ directions. .. tip:: A common mistake here is to type the names of the animations wrong. The animation names in the SpriteFrames panel must match what you type in - the code. If you named the animation ``"Walk"``, you must also use a + the code. If you named the animation `"Walk"`, you must also use a capital "W" in the code. When you're sure the movement is working correctly, add this line to -``_ready()``, so the player will be hidden when the game starts: +`_ready()`, so the player will be hidden when the game starts: gdscript GDScript @@ -232,11 +232,11 @@ gdscript GDScript Preparing for collisions ~~~~~~~~~~~~~~~~~~~~~~~~ -We want ``Player`` to detect when it's hit by an enemy, but we haven't made any +We want `Player` to detect when it's hit by an enemy, but we haven't made any enemies yet! That's OK, because we're going to use Godot's *signal* functionality to make it work. -Add the following at the top of the script, after ``extends Area2D``: +Add the following at the top of the script, after `extends Area2D`: gdscript GDScript @@ -245,14 +245,14 @@ gdscript GDScript ``` This defines a custom signal called "hit" that we will have our player emit -(send out) when it collides with an enemy. We will use ``Area2D`` to detect the -collision. Select the ``Player`` node and click the "Node" tab next to the +(send out) when it collides with an enemy. We will use `Area2D` to detect the +collision. Select the `Player` node and click the "Node" tab next to the Inspector tab to see the list of signals the player can emit: .. image:: img/player_signals.png Notice our custom "hit" signal is there as well! Since our enemies are going to -be ``RigidBody2D`` nodes, we want the ``body_entered(body: Node)`` signal. This +be `RigidBody2D` nodes, we want the `body_entered(body: Node)` signal. This signal will be emitted when a body contacts the player. Click "Connect.." and the "Connect a Signal" window appears. We don't need to change any of these settings so click "Connect" again. Godot will automatically create a function in @@ -274,12 +274,12 @@ gdscript GDScript ``` 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 +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 in the middle of the engine's collision processing. Using - ``set_deferred()`` tells Godot to wait to disable the shape until it's + `set_deferred()` tells Godot to wait to disable the shape until it's safe to do so. The last piece is to add a function we can call to reset the player when diff --git a/getting_started/first_2d_game/04.creating_the_enemy.rst b/getting_started/first_2d_game/04.creating_the_enemy.rst index 9f2b826..decb7a8 100644 --- a/getting_started/first_2d_game/04.creating_the_enemy.rst +++ b/getting_started/first_2d_game/04.creating_the_enemy.rst @@ -7,7 +7,7 @@ Now it's time to make the enemies our player will have to dodge. Their behavior will not be very complex: mobs will spawn randomly at the edges of the screen, choose a random direction, and move in a straight line. -We'll create a ``Mob`` scene, which we can then *instance* to create any number +We'll create a `Mob` scene, which we can then *instance* to create any number of independent mobs in the game. Node setup @@ -15,7 +15,7 @@ Node setup Click Scene -> New Scene and add the following nodes: -- `RigidBody2D` (named ``Mob``) +- `RigidBody2D` (named `Mob`) - `AnimatedSprite` - `CollisionShape2D` @@ -24,39 +24,39 @@ Click Scene -> New Scene and add the following nodes: Don't forget to set the children so they can't be selected, like you did with the Player scene. -In the `RigidBody2D` properties, set ``Gravity Scale`` -to ``0``, so the mob will not fall downward. In addition, under the -`CollisionObject2D` section, click the ``Mask`` property and uncheck the first +In the `RigidBody2D` properties, set `Gravity Scale` +to `0`, so the mob will not fall downward. In addition, under the +`CollisionObject2D` section, click the `Mask` property and uncheck the first box. This will ensure the mobs do not collide with each other. .. image:: img/set_collision_mask.png Set up the `AnimatedSprite` like you did for the -player. This time, we have 3 animations: ``fly``, ``swim``, and ``walk``. There +player. This time, we have 3 animations: `fly`, `swim`, and `walk`. There are two images for each animation in the art folder. -Adjust the "Speed (FPS)" to ``3`` for all animations. +Adjust the "Speed (FPS)" to `3` for all animations. .. image:: img/mob_animations.gif -Set the ``Playing`` property in the Inspector to "On". +Set the `Playing` property in the Inspector to "On". We'll select one of these animations randomly so that the mobs will have some variety. Like the player images, these mob images need to be scaled down. Set the -``AnimatedSprite``'s ``Scale`` property to ``(0.75, 0.75)``. +`AnimatedSprite`'s `Scale` property to `(0.75, 0.75)`. -As in the ``Player`` scene, add a ``CapsuleShape2D`` for the collision. To align -the shape with the image, you'll need to set the ``Rotation Degrees`` property -to ``90`` (under "Transform" in the Inspector). +As in the `Player` scene, add a `CapsuleShape2D` for the collision. To align +the shape with the image, you'll need to set the `Rotation Degrees` property +to `90` (under "Transform" in the Inspector). Save the scene. Enemy script ~~~~~~~~~~~~ -Add a script to the ``Mob`` like this: +Add a script to the `Mob` like this: gdscript GDScript @@ -64,7 +64,7 @@ gdscript GDScript extends RigidBody2D ``` -Now let's look at the rest of the script. In ``_ready()`` we play the animation +Now let's look at the rest of the script. In `_ready()` we play the animation and randomly choose one of the three animation types: gdscript GDScript @@ -76,20 +76,20 @@ gdscript GDScript $AnimatedSprite.animation = mob_types[randi() % mob_types.size()] ``` -First, we get the list of animation names from the AnimatedSprite's ``frames`` -property. This returns an Array containing all three animation names: ``["walk", -"swim", "fly"]``. +First, we get the list of animation names from the AnimatedSprite's `frames` +property. This returns an Array containing all three animation names: `["walk", +"swim", "fly"]`. -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``. +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. + use `randomize()` in our `Main` scene, so we won't need it here. The last piece is to make the mobs delete themselves when they leave the screen. -Connect the ``screen_exited()`` signal of the ``VisibilityNotifier2D`` node and +Connect the `screen_exited()` signal of the `VisibilityNotifier2D` node and add this code: gdscript GDScript diff --git a/getting_started/first_2d_game/05.the_main_game_scene.rst b/getting_started/first_2d_game/05.the_main_game_scene.rst index 3b3c471..544aecb 100644 --- a/getting_started/first_2d_game/05.the_main_game_scene.rst +++ b/getting_started/first_2d_game/05.the_main_game_scene.rst @@ -5,42 +5,42 @@ The main game scene Now it's time to bring everything we did together into a playable game scene. -Create a new scene and add a `Node` named ``Main``. +Create a new scene and add a `Node` named `Main`. (The reason we are using Node instead of Node2D is because this node will be a container for handling game logic. It does not require 2D functionality itself.) Click the **Instance** button (represented by a chain link icon) and select your saved -``Player.tscn``. +`Player.tscn`. .. image:: img/instance_scene.png -Now, add the following nodes as children of ``Main``, and name them as shown +Now, add the following nodes as children of `Main`, and name them as shown (values are in seconds): -- `Timer` (named ``MobTimer``) - to control how often mobs +- `Timer` (named `MobTimer`) - to control how often mobs spawn -- `Timer` (named ``ScoreTimer``) - to increment the score +- `Timer` (named `ScoreTimer`) - to increment the score every second -- `Timer` (named ``StartTimer``) - to give a delay before +- `Timer` (named `StartTimer`) - to give a delay before starting -- `Position2D` (named ``StartPosition``) - to indicate +- `Position2D` (named `StartPosition`) - to indicate the player's start position -Set the ``Wait Time`` property of each of the ``Timer`` nodes as follows: +Set the `Wait Time` property of each of the `Timer` nodes as follows: -- ``MobTimer``: ``0.5`` -- ``ScoreTimer``: ``1`` -- ``StartTimer``: ``2`` +- `MobTimer`: `0.5` +- `ScoreTimer`: `1` +- `StartTimer`: `2` -In addition, set the ``One Shot`` property of ``StartTimer`` to "On" and set -``Position`` of the ``StartPosition`` node to ``(240, 450)``. +In addition, set the `One Shot` property of `StartTimer` to "On" and set +`Position` of the `StartPosition` node to `(240, 450)`. Spawning mobs ~~~~~~~~~~~~~ The Main node will be spawning new mobs, and we want them to appear at a random location on the edge of the screen. Add a `Path2D` node -named ``MobPath`` as a child of ``Main``. When you select ``Path2D``, you will +named `MobPath` as a child of `Main`. When you select `Path2D`, you will see some new buttons at the top of the editor: .. image:: img/path2d_buttons.png @@ -58,11 +58,11 @@ intersecting lines, respectively. .. image:: img/draw_path2d.gif -After placing point ``4`` in the image, click the "Close Curve" button and your +After placing point `4` in the image, click the "Close Curve" button and your curve will be complete. Now that the path is defined, add a `PathFollow2D` -node as a child of ``MobPath`` and name it ``MobSpawnLocation``. This node will +node as a child of `MobPath` and name it `MobSpawnLocation`. This node will automatically rotate and follow the path as it moves, so we can use it to select a random position and direction along the path. @@ -73,8 +73,8 @@ Your scene should look like this: Main script ~~~~~~~~~~~ -Add a script to ``Main``. At the top of the script, we use ``export -(PackedScene)`` to allow us to choose the Mob scene we want to instance. +Add a script to `Main`. At the top of the script, we use `export +(PackedScene)` to allow us to choose the Mob scene we want to instance. gdscript GDScript @@ -85,7 +85,7 @@ gdscript GDScript var score ``` -We also add a call to ``randomize()`` here so that the random number +We also add a call to `randomize()` here so that the random number generator generates different random numbers each time the game is run: gdscript GDScript @@ -95,25 +95,25 @@ gdscript GDScript randomize() ``` -Click the ``Main`` node and you will see the ``Mob Scene`` property in the Inspector +Click the `Main` node and you will see the `Mob Scene` property in the Inspector under "Script Variables". You can assign this property's value in two ways: -- Drag ``Mob.tscn`` from the "FileSystem" dock and drop it in the **Mob Scene** +- Drag `Mob.tscn` from the "FileSystem" dock and drop it in the **Mob Scene** property. -- Click the down arrow next to "[empty]" and choose "Load". Select ``Mob.tscn``. +- Click the down arrow next to "[empty]" and choose "Load". Select `Mob.tscn`. -Next, select the ``Player`` node in the Scene dock, and access the Node dock on +Next, select the `Player` node in the Scene dock, and access the Node dock on the sidebar. Make sure to have the Signals tab selected in the Node dock. -You should see a list of the signals for the ``Player`` node. Find and -double-click the ``hit`` signal in the list (or right-click it and select +You should see a list of the signals for the `Player` node. Find and +double-click the `hit` signal in the list (or right-click it and select "Connect..."). This will open the signal connection dialog. We want to make a -new function named ``game_over``, which will handle what needs to happen when a +new function named `game_over`, which will handle what needs to happen when a game ends. Type "game_over" in the "Receiver Method" box at the bottom of the signal connection dialog and click "Connect". Add the following code to the new -function, as well as a ``new_game`` function that will set everything up for a +function, as well as a `new_game` function that will set everything up for a new game: gdscript GDScript @@ -129,9 +129,9 @@ gdscript GDScript $StartTimer.start() ``` -Now connect the ``timeout()`` signal of each of the Timer nodes (``StartTimer``, -``ScoreTimer`` , and ``MobTimer``) to the main script. ``StartTimer`` will start -the other two timers. ``ScoreTimer`` will increment the score by 1. +Now connect the `timeout()` signal of each of the Timer nodes (`StartTimer`, +`ScoreTimer` , and `MobTimer`) to the main script. `StartTimer` will start +the other two timers. `ScoreTimer` will increment the score by 1. gdscript GDScript @@ -144,15 +144,15 @@ gdscript GDScript $ScoreTimer.start() ``` -In ``_on_MobTimer_timeout()``, we will create a mob instance, pick a random -starting location along the ``Path2D``, and set the mob in motion. The -``PathFollow2D`` node will automatically rotate as it follows the path, so we +In `_on_MobTimer_timeout()`, we will create a mob instance, pick a random +starting location along the `Path2D`, and set the mob in motion. The +`PathFollow2D` node will automatically rotate as it follows the path, so we will use that to select the mob's direction as well as its position. -When we spawn a mob, we'll pick a random value between ``150.0`` and -``250.0`` for how fast each mob will move (it would be boring if they were +When we spawn a mob, we'll pick a random value between `150.0` and +`250.0` for how fast each mob will move (it would be boring if they were all moving at the same speed). -Note that a new instance must be added to the scene using ``add_child()``. +Note that a new instance must be added to the scene using `add_child()`. gdscript GDScript @@ -183,18 +183,18 @@ gdscript GDScript add_child(mob) ``` -.. important:: Why ``PI``? In functions requiring angles, Godot uses *radians*, +.. important:: Why `PI`? In functions requiring angles, Godot uses *radians*, not degrees. Pi represents a half turn in radians, about - ``3.1415`` (there is also ``TAU`` which is equal to ``2 * PI``). + `3.1415` (there is also `TAU` which is equal to `2 * PI`). If you're more comfortable working with degrees, you'll need to - use the ``deg2rad()`` and ``rad2deg()`` functions to convert + use the `deg2rad()` and `rad2deg()` functions to convert between the two. Testing the scene ~~~~~~~~~~~~~~~~~ -Let's test the scene to make sure everything is working. Add this ``new_game`` -call to ``_ready()``: +Let's test the scene to make sure everything is working. Add this `new_game` +call to `_ready()`: gdscript GDScript @@ -204,18 +204,18 @@ gdscript GDScript new_game() ``` -Let's also assign ``Main`` as our "Main Scene" - the one that runs automatically -when the game launches. Press the "Play" button and select ``Main.tscn`` when +Let's also assign `Main` as our "Main Scene" - the one that runs automatically +when the game launches. Press the "Play" button and select `Main.tscn` when prompted. .. tip:: If you had already set another scene as the "Main Scene", you can right - click ``Main.tscn`` in the FileSystem dock and select "Set As Main Scene". + click `Main.tscn` in the FileSystem dock and select "Set As Main Scene". You should be able to move the player around, see mobs spawning, and see the player disappear when hit by a mob. -When you're sure everything is working, remove the call to ``new_game()`` from -``_ready()``. +When you're sure everything is working, remove the call to `new_game()` from +`_ready()`. What's our game lacking? Some user interface. In the next lesson, we'll add a title screen and display the player's score. diff --git a/getting_started/first_2d_game/06.heads_up_display.rst b/getting_started/first_2d_game/06.heads_up_display.rst index 12d4c5e..b1ea13b 100644 --- a/getting_started/first_2d_game/06.heads_up_display.rst +++ b/getting_started/first_2d_game/06.heads_up_display.rst @@ -7,7 +7,7 @@ The final piece our game needs is a User Interface (UI) to display things like score, a "game over" message, and a restart button. Create a new scene, and add a `CanvasLayer` node named -``HUD``. "HUD" stands for "heads-up display", an informational display that +`HUD`. "HUD" stands for "heads-up display", an informational display that appears as an overlay on top of the game view. The `CanvasLayer` node lets us draw our UI elements on @@ -16,7 +16,7 @@ covered up by any game elements like the player or mobs. The HUD needs to display the following information: -- Score, changed by ``ScoreTimer``. +- Score, changed by `ScoreTimer`. - A message, such as "Game Over" or "Get Ready!" - A "Start" button to begin the game. @@ -24,15 +24,15 @@ The basic node for UI elements is `Control`. To create our UI, we'll use two types of `Control` nodes: `Label ` and `Button`. -Create the following as children of the ``HUD`` node: +Create the following as children of the `HUD` node: -- `Label` named ``ScoreLabel``. -- `Label` named ``Message``. -- `Button` named ``StartButton``. -- `Timer` named ``MessageTimer``. +- `Label` named `ScoreLabel`. +- `Label` named `Message`. +- `Button` named `StartButton`. +- `Timer` named `MessageTimer`. -Click on the ``ScoreLabel`` and type a number into the ``Text`` field in the -Inspector. The default font for ``Control`` nodes is small and doesn't scale +Click on the `ScoreLabel` and type a number into the `Text` field in the +Inspector. The default font for `Control` nodes is small and doesn't scale well. There is a font file included in the game assets called "Xolonium-Regular.ttf". To use this font, do the following: @@ -45,15 +45,15 @@ well. There is a font file included in the game assets called .. image:: img/custom_font2.png -Set the "Size" property under ``Settings``, ``64`` works well. +Set the "Size" property under `Settings`, `64` works well. .. image:: img/custom_font3.png -Once you've done this on the ``ScoreLabel``, you can click the down arrow next +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 @@ -71,31 +71,31 @@ ScoreLabel ~~~~~~~~~~ - *Layout* : "Top Wide" -- *Text* : ``0`` +- *Text* : `0` - *Align* : "Center" Message ~~~~~~~~~~~~ - *Layout* : "HCenter Wide" -- *Text* : ``Dodge the Creeps!`` +- *Text* : `Dodge the Creeps!` - *Align* : "Center" - *Autowrap* : "On" StartButton ~~~~~~~~~~~ -- *Text* : ``Start`` +- *Text* : `Start` - *Layout* : "Center Bottom" - *Margin* : - - Top: ``-200`` - - Bottom: ``-100`` + - Top: `-200` + - Bottom: `-100` -On the ``MessageTimer``, set the ``Wait Time`` to ``2`` and set the ``One Shot`` +On the `MessageTimer`, set the `Wait Time` to `2` and set the `One Shot` property to "On". -Now add this script to ``HUD``: +Now add this script to `HUD`: gdscript GDScript @@ -105,7 +105,7 @@ gdscript GDScript signal start_game ``` -The ``start_game`` signal tells the ``Main`` node that the button +The `start_game` signal tells the `Main` node that the button has been pressed. gdscript GDScript @@ -140,7 +140,7 @@ 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 - Timer node is to use the SceneTree's ``create_timer()`` function. This + 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. @@ -151,10 +151,10 @@ gdscript GDScript $ScoreLabel.text = str(score) ``` -This function is called by ``Main`` whenever the score changes. +This function is called by `Main` whenever the score changes. -Connect the ``timeout()`` signal of ``MessageTimer`` and the ``pressed()`` -signal of ``StartButton`` and add the following code to the new functions: +Connect the `timeout()` signal of `MessageTimer` and the `pressed()` +signal of `StartButton` and add the following code to the new functions: gdscript GDScript @@ -170,21 +170,21 @@ gdscript GDScript Connecting HUD to Main ~~~~~~~~~~~~~~~~~~~~~~ -Now that we're done creating the ``HUD`` scene, go back to ``Main``. Instance -the ``HUD`` scene in ``Main`` like you did the ``Player`` scene. The scene tree +Now that we're done creating the `HUD` scene, go back to `Main`. Instance +the `HUD` scene in `Main` like you did the `Player` scene. The scene tree should look like this, so make sure you didn't miss anything: .. image:: img/completed_main_scene.png -Now we need to connect the ``HUD`` functionality to our ``Main`` script. This -requires a few additions to the ``Main`` scene: +Now we need to connect the `HUD` functionality to our `Main` script. This +requires a few additions to the `Main` scene: -In the Node tab, connect the HUD's ``start_game`` signal to the ``new_game()`` +In the Node tab, connect the HUD's `start_game` signal to the `new_game()` function of the Main node by typing "new_game" in the "Receiver Method" in the "Connect a Signal" window. Verify that the green connection icon now appears -next to ``func new_game()`` in the script. +next to `func new_game()` in the script. -In ``new_game()``, update the score display and show the "Get Ready" message: +In `new_game()`, update the score display and show the "Get Ready" message: gdscript GDScript @@ -193,7 +193,7 @@ gdscript GDScript $HUD.show_message("Get Ready") ``` -In ``game_over()`` we need to call the corresponding ``HUD`` function: +In `game_over()` we need to call the corresponding `HUD` function: gdscript GDScript @@ -201,7 +201,7 @@ gdscript GDScript $HUD.show_game_over() ``` -Finally, add this to ``_on_ScoreTimer_timeout()`` to keep the display in sync +Finally, add this to `_on_ScoreTimer_timeout()` to keep the display in sync with the changing score: gdscript GDScript @@ -211,7 +211,7 @@ gdscript GDScript ``` Now you're ready to play! Click the "Play the Project" button. You will be asked -to select a main scene, so choose ``Main.tscn``. +to select a main scene, so choose `Main.tscn`. Removing old creeps ~~~~~~~~~~~~~~~~~~~ @@ -221,14 +221,14 @@ from the previous game may still be on the screen. It would be better if they all disappeared at the start of a new game. We just need a way to tell *all* the mobs to remove themselves. We can do this with the "group" feature. -In the ``Mob`` scene, select the root node and click the "Node" tab next to the +In the `Mob` scene, select the root node and click the "Node" tab next to the Inspector (the same place where you find the node's signals). Next to "Signals", click "Groups" and you can type a new group name and click "Add". .. image:: img/group_tab.png Now all mobs will be in the "mobs" group. We can then add the following line to -the ``new_game()`` function in ``Main``: +the `new_game()` function in `Main`: gdscript GDScript @@ -236,7 +236,7 @@ gdscript GDScript get_tree().call_group("mobs", "queue_free") ``` -The ``call_group()`` function calls the named function on every node in a +The `call_group()` function calls the named function on every node in a group - in this case we are telling every mob to delete itself. The game's mostly done at this point. In the next and last part, we'll polish it diff --git a/getting_started/first_2d_game/07.finishing-up.rst b/getting_started/first_2d_game/07.finishing-up.rst index fd76154..42aa9a3 100644 --- a/getting_started/first_2d_game/07.finishing-up.rst +++ b/getting_started/first_2d_game/07.finishing-up.rst @@ -13,12 +13,12 @@ Background The default gray background is not very appealing, so let's change its color. One way to do this is to use a `ColorRect` node. Make it -the first node under ``Main`` so that it will be drawn behind the other nodes. -``ColorRect`` only has one property: ``Color``. Choose a color you like and +the first node under `Main` so that it will be drawn behind the other nodes. +`ColorRect` only has one property: `Color`. Choose a color you like and select "Layout" -> "Full Rect" so that it covers the screen. You could also add a background image, if you have one, by using a -``TextureRect`` node instead. +`TextureRect` node instead. Sound effects ~~~~~~~~~~~~~ @@ -29,35 +29,35 @@ Forest Loop.ogg" for background music, and "gameover.wav" for when the player loses. Add two `AudioStreamPlayer` nodes as children of -``Main``. Name one of them ``Music`` and the other ``DeathSound``. On each one, -click on the ``Stream`` property, select "Load", and choose the corresponding +`Main`. Name one of them `Music` and the other `DeathSound`. On each one, +click on the `Stream` property, select "Load", and choose the corresponding audio file. -To play the music, add ``$Music.play()`` in the ``new_game()`` function and -``$Music.stop()`` in the ``game_over()`` function. +To play the music, add `$Music.play()` in the `new_game()` function and +`$Music.stop()` in the `game_over()` function. -Finally, add ``$DeathSound.play()`` in the ``game_over()`` function. +Finally, add `$DeathSound.play()` in the `game_over()` function. Keyboard shortcut ~~~~~~~~~~~~~~~~~ Since the game is played with keyboard controls, it would be convenient if we could also start the game by pressing a key on the keyboard. We can do this with -the "Shortcut" property of the ``Button`` node. +the "Shortcut" property of the `Button` node. In a previous lesson, we created four input actions to move the character. We will create a similar input action to map to the start button. Select "Project" -> "Project Settings" and then click on the "Input Map" tab. In the same way you created the movement input actions, create a new -input action called ``start_game`` and add a key mapping for the :kbd:`Enter` +input action called `start_game` and add a key mapping for the :kbd:`Enter` key. -In the ``HUD`` scene, select the ``StartButton`` and find its *Shortcut* +In the `HUD` scene, select the `StartButton` and find its *Shortcut* property in the Inspector. Select "New Shortcut" and click on the "Shortcut" item. A second *Shortcut* property will appear. Select "New InputEventAction" and click the new "InputEventAction". Finally, in the *Action* property, type -the name ``start_game``. +the name `start_game`. .. image:: img/start_button_shortcut.png diff --git a/getting_started/first_3d_game/01.game_setup.rst b/getting_started/first_3d_game/01.game_setup.rst index 9f19cd0..5a0b81f 100644 --- a/getting_started/first_3d_game/01.game_setup.rst +++ b/getting_started/first_3d_game/01.game_setup.rst @@ -17,8 +17,8 @@ Godot project manager and click the *Import* button. |image1| In the import popup, enter the full path to the freshly created directory -``squash_the_creeps_start/``. You can click the *Browse* button on the right to -open a file browser and navigate to the ``project.godot`` file the folder +`squash_the_creeps_start/`. You can click the *Browse* button on the right to +open a file browser and navigate to the `project.godot` file the folder contains. |image2| @@ -27,12 +27,12 @@ Click *Import & Edit* to open the project in the editor. |image3| -The start project contains an icon and two folders: ``art/`` and ``fonts/``. +The start project contains an icon and two folders: `art/` and `fonts/`. There, you will find the art assets and music we'll use in the game. |image4| -There are two 3D models, ``player.glb`` and ``mob.glb``, some materials that +There are two 3D models, `player.glb` and `mob.glb`, some materials that belong to these models, and a music track. Setting up the playable area @@ -45,7 +45,7 @@ a node to the scene, you can press :kbd:`Ctrl + a` (or :kbd:`Cmd + a` on macOS). |image5| -Save the scene as ``Main.tscn`` by pressing :kbd:`Ctrl + s` (:kbd:`Cmd + s` on macOS). +Save the scene as `Main.tscn` by pressing :kbd:`Ctrl + s` (:kbd:`Cmd + s` on macOS). We'll start by adding a floor that'll prevent the characters from falling. To create static colliders like the floor, walls, or ceilings, you can use @@ -72,7 +72,7 @@ reliable to block even fast-moving objects. A box's wireframe appears in the viewport with three orange dots. You can click and drag these to edit the shape's extents interactively. We can also precisely set the size in the inspector. Click on the *BoxShape* to expand the resource. -Set its *Extents* to ``30`` on the X axis, ``1`` for the Y axis, and ``30`` for +Set its *Extents* to `30` on the X axis, `1` for the Y axis, and `30` for the Z axis. |image9| @@ -80,7 +80,7 @@ the Z axis. .. 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`` + twice its extents: `60` by `60` meters on the ground plane and `2` units tall. The ground plane is defined by the X and Z axes, while the Y axis represents the height. @@ -95,7 +95,7 @@ resource to create a visible cube. |image11| Once again, it's too small by default. Click the cube icon to expand the -resource and set its *Size* to ``60``, ``2``, and ``60``. As the cube +resource and set its *Size* to `60`, `2`, and `60`. As the cube resource works with a size rather than extents, we need to use these values so it matches our collision shape. @@ -117,7 +117,7 @@ and click and drag down on the Y axis. It's the green arrow in the move gizmo. |image14| -Move the ground down ``1`` meter. A label in the bottom-left corner of the +Move the ground down `1` meter. A label in the bottom-left corner of the viewport tells you how much you're translating the node. |image15| diff --git a/getting_started/first_3d_game/02.player_input.rst b/getting_started/first_3d_game/02.player_input.rst index 42d1162..b06fb53 100644 --- a/getting_started/first_3d_game/02.player_input.rst +++ b/getting_started/first_3d_game/02.player_input.rst @@ -30,8 +30,8 @@ For now, we're going to create a basic rig for our character's 3D model. This will allow us to rotate the model later via code while it plays an animation. Add a *Spatial* node as a child of *Player* and name it *Pivot*. Then, in the -FileSystem dock, expand the ``art/`` folder by double-clicking it and drag and -drop ``player.glb`` onto the *Pivot* node. +FileSystem dock, expand the `art/` folder by double-clicking it and drag and +drop `player.glb` onto the *Pivot* node. |image1| @@ -42,7 +42,7 @@ This should instantiate the model as a child of *Pivot*. You can rename it to .. note:: - The ``.glb`` files contain 3D scene data based on the open-source GLTF 2.0 + 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 like FBX, which Godot also supports. To produce these files, we designed the model in `Blender 3D `__ and exported it to GLTF. @@ -56,7 +56,7 @@ property. The sphere's wireframe appears below the character. It will be the shape the physics engine uses to collide with the environment, so we want it to better fit the 3D model. Shrink it a bit by dragging the orange -dot in the viewport. My sphere has a radius of about ``0.8`` meters. +dot in the viewport. My sphere has a radius of about `0.8` meters. Then, move the shape up so its bottom roughly aligns with the grid's plane. @@ -67,7 +67,7 @@ You can toggle the model's visibility by clicking the eye icon next to the |image5| -Save the scene as ``Player.tscn``. +Save the scene as `Player.tscn`. With the nodes ready, we can almost get coding. But first, we need to define some input actions. @@ -94,8 +94,8 @@ can bind keys to these actions. Godot projects come with some predefined actions designed for user interface design, which we could use here. But we're defining our own to support gamepads. -We're going to name our actions ``move_left``, ``move_right``, ``move_forward``, -``move_back``, and ``jump``. +We're going to name our actions `move_left`, `move_right`, `move_forward`, +`move_back`, and `jump`. To add an action, write its name in the bar at the top and press Enter. @@ -106,7 +106,7 @@ Create the five actions. Your window should have them all listed at the bottom. |image9| To bind a key or button to an action, click the "+" button to its right. Do this -for ``move_left`` and in the drop-down menu, click *Key*. +for `move_left` and in the drop-down menu, click *Key*. |image10| @@ -133,12 +133,12 @@ press the *Add* button. |image14| Do the same for the other input actions. For example, bind the right arrow, D, -and the left joystick's right axis to ``move_right``. After binding all keys, +and the left joystick's right axis to `move_right`. After binding all keys, your interface should look like this. |image15| -We have the ``jump`` action left to set up. Bind the Space key and the gamepad's +We have the `jump` action left to set up. Bind the Space key and the gamepad's A button. To bind a gamepad's button, select the *Joy Button* option in the menu. |image16| diff --git a/getting_started/first_3d_game/03.player_movement_code.rst b/getting_started/first_3d_game/03.player_movement_code.rst index 484ffcc..25cda65 100644 --- a/getting_started/first_3d_game/03.player_movement_code.rst +++ b/getting_started/first_3d_game/03.player_movement_code.rst @@ -30,7 +30,7 @@ gdscript GDScript ``` -These are common properties for a moving body. The ``velocity`` is a 3D vector +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. @@ -41,7 +41,7 @@ we want to update and reuse its value across frames. screen's width, in 3D, it's a kilometer. Let's code the movement now. We start by calculating the input direction vector -using the global ``Input`` object, in ``_physics_process()``. +using the global `Input` object, in `_physics_process()`. gdscript GDScript @@ -63,27 +63,27 @@ gdscript GDScript direction.z -= 1 ``` -Here, we're going to make all calculations using the ``_physics_process()`` -virtual function. Like ``_process()``, it allows you to update the node every +Here, we're going to make all calculations using the `_physics_process()` +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:: - To learn more about the difference between ``_process()`` and - ``_physics_process()``, see `doc_idle_and_physics_processing`. + To learn more about the difference between `_process()` and + `_physics_process()`, see `doc_idle_and_physics_processing`. -We start by initializing a ``direction`` variable to ``Vector3.ZERO``. Then, we -check if the player is pressing one or more of the ``move_*`` inputs and update -the vector's ``x`` and ``z`` components accordingly. These correspond to the +We start by initializing a `direction` variable to `Vector3.ZERO`. Then, we +check if the player is pressing one or more of the `move_*` inputs and update +the vector's `x` and `z` components accordingly. These correspond to the ground plane's axes. These four conditions give us eight possibilities and eight possible directions. In case the player presses, say, both W and D simultaneously, the vector will -have a length of about ``1.4``. But if they press a single key, it will have a -length of ``1``. We want the vector's length to be consistent. To do so, we can -call its ``normalize()`` method. +have a length of about `1.4`. But if they press a single key, it will have a +length of `1`. We want the vector's length to be consistent. To do so, we can +call its `normalize()` method. gdscript GDScript @@ -99,23 +99,23 @@ gdscript GDScript Here, we only normalize the vector if the direction has a length greater than zero, which means the player is pressing a direction key. -In this case, we also get the *Pivot* node and call its ``look_at()`` method. +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. +up direction. In this case, we can use the `Vector3.UP` constant. .. note:: - A node's local coordinates, like ``translation``, are relative to their + 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 in the viewport instead. -In 3D, the property that contains a node's position is ``translation``. By -adding the ``direction`` to it, we get a position to look at that's one meter +In 3D, the property that contains a node's position is `translation`. By +adding the `direction` to it, we get a position to look at that's one meter away from the *Player*. Then, we update the velocity. We have to calculate the ground velocity and the fall speed separately. Be sure to go back one tab so the lines are inside the -``_physics_process()`` function but outside the condition we just wrote. +`_physics_process()` function but outside the condition we just wrote. gdscript GDScript @@ -135,8 +135,8 @@ gdscript GDScript ``` For the vertical velocity, we subtract the fall acceleration multiplied by the -delta time every frame. Notice the use of the ``-=`` operator, which is a -shorthand for ``variable = variable - ...``. +delta time every frame. Notice the use of the `-=` operator, which is a +shorthand for `variable = variable - ...`. This line of code will cause our character to fall in every frame. This may seem strange if it's already on the floor. But we have to do this for the character @@ -146,8 +146,8 @@ The physics engine can only detect interactions with walls, the floor, or other bodies during a given frame if movement and collisions happen. We will use this property later to code the jump. -On the last line, we call ``KinematicBody.move_and_slide()``. It's a powerful -method of the ``KinematicBody`` class that allows you to move a character +On the last line, we call `KinematicBody.move_and_slide()`. It's a powerful +method of the `KinematicBody` class that allows you to move a character smoothly. If it hits a wall midway through a motion, the engine will try to smooth it out for you. @@ -160,7 +160,7 @@ big the character would move through the ground slab after a while. And that's all the code you need to move the character on the floor. -Here is the complete ``Player.gd`` code for reference. +Here is the complete `Player.gd` code for reference. gdscript GDScript @@ -210,7 +210,7 @@ tab at the top of the editor to do so. |image1| If you closed the scene before, head to the *FileSystem* dock and double-click -``Main.tscn`` to re-open it. +`Main.tscn` to re-open it. To instantiate the *Player*, right-click on the *Main* node and select *Instance Child Scene*. @@ -249,12 +249,12 @@ the checkbox. |image6| -In the top view, move the camera about ``19`` units on the Z axis (the blue +In the top view, move the camera about `19` units on the Z axis (the blue one). |image7| -Here's where the magic happens. Select the *CameraPivot* and rotate it ``45`` +Here's where the magic happens. Select the *CameraPivot* and rotate it `45` degrees around the X axis (using the red circle). You'll see the camera move as if it was attached to a crane. @@ -271,7 +271,7 @@ to better frame the gameplay area and make it easier for the player to read distances. Select the *Camera* again and in the *Inspector*, set the *Projection* to -*Orthogonal* and the *Size* to ``19``. The character should now look flatter and +*Orthogonal* and the *Size* to `19`. The character should now look flatter and the ground should fill the background. |image10| diff --git a/getting_started/first_3d_game/04.mob_scene.rst b/getting_started/first_3d_game/04.mob_scene.rst index e91b0c7..a60d3cc 100644 --- a/getting_started/first_3d_game/04.mob_scene.rst +++ b/getting_started/first_3d_game/04.mob_scene.rst @@ -11,7 +11,7 @@ to be similar to the *Player* scene. Create a scene with, once again, a *KinematicBody* node as its root. Name it *Mob*. Add a *Spatial* node as a child of it, name it *Pivot*. And drag and drop -the file ``mob.glb`` from the *FileSystem* dock onto the *Pivot* to add the +the file `mob.glb` from the *FileSystem* dock onto the *Pivot* to add the monster's 3D model to the scene. You can rename the newly created *mob* node into *Character*. @@ -93,9 +93,9 @@ Attach a script to the *Mob*. |image7| -Here's the movement code to start with. We define two properties, ``min_speed`` -and ``max_speed``, to define a random speed range. We then define and initialize -the ``velocity``. +Here's the movement code to start with. We define two properties, `min_speed` +and `max_speed`, to define a random speed range. We then define and initialize +the `velocity`. gdscript GDScript @@ -115,28 +115,28 @@ gdscript GDScript ``` Similarly to the player, we move the mob every frame by calling -``KinematicBody``\ 's ``move_and_slide()`` method. This time, we don't update -the ``velocity`` every frame: we want the monster to move at a constant speed +`KinematicBody`\ 's `move_and_slide()` method. This time, we don't update +the `velocity` every frame: we want the monster to move at a constant speed and leave the screen, even if it were to hit an obstacle. You may see a warning in GDScript that the return value from -``move_and_slide()`` is unused. This is expected. You can simply ignore the +`move_and_slide()` is unused. This is expected. You can simply ignore the warning or, if you want to hide it entirely, add the comment -``# warning-ignore:return_value_discarded`` just above the -``move_and_slide(velocity)`` line. To read more about the GDScript warning +`# warning-ignore:return_value_discarded` just above the +`move_and_slide(velocity)` line. To read more about the GDScript warning system, see `doc_gdscript_warning_system`. We need to define another function to calculate the start velocity. This function will turn the monster towards the player and randomize both its angle of motion and its velocity. -The function will take a ``start_position``, the mob's spawn position, and the -``player_position`` as its arguments. +The function will take a `start_position`, the mob's spawn position, and the +`player_position` as its arguments. -We position the mob at ``start_position`` and turn it towards the player using -the ``look_at_from_position()`` method, and randomize the angle by rotating a -random amount around the Y axis. Below, ``rand_range()`` outputs a random value -between ``-PI / 4`` radians and ``PI / 4`` radians. +We position the mob at `start_position` and turn it towards the player using +the `look_at_from_position()` method, and randomize the angle by rotating a +random amount around the Y axis. Below, `rand_range()` outputs a random value +between `-PI / 4` radians and `PI / 4` radians. gdscript GDScript @@ -149,12 +149,12 @@ gdscript GDScript rotate_y(rand_range(-PI / 4, PI / 4)) ``` -We then calculate a random speed using ``rand_range()`` once again and we use it +We then calculate a random speed using `rand_range()` once again and we use it to calculate the velocity. We start by creating a 3D vector pointing forward, multiply it by our -``random_speed``, and finally rotate it using the ``Vector3`` class's -``rotated()`` method. +`random_speed`, and finally rotate it using the `Vector3` class's +`rotated()` method. gdscript GDScript @@ -174,7 +174,7 @@ Leaving the screen ------------------ We still have to destroy the mobs when they leave the screen. To do so, we'll -connect our *VisibilityNotifier* node's ``screen_exited`` signal to the *Mob*. +connect our *VisibilityNotifier* node's `screen_exited` signal to the *Mob*. Head back to the 3D viewport by clicking on the *3D* label at the top of the editor. You can also press :kbd:`Ctrl + F2` (:kbd:`Alt + 2` on macOS). @@ -191,7 +191,7 @@ Connect the signal to the *Mob*. |image10| This will take you back to the script editor and add a new function for you, -``_on_VisibilityNotifier_screen_exited()``. From it, call the ``queue_free()`` +`_on_VisibilityNotifier_screen_exited()`. From it, call the `queue_free()` method. This will destroy the mob instance when the *VisibilityNotifier* \'s box leaves the screen. @@ -205,7 +205,7 @@ gdscript GDScript Our monster is ready to enter the game! In the next part, you will spawn monsters in the game level. -Here is the complete ``Mob.gd`` script for reference. +Here is the complete `Mob.gd` script for reference. gdscript GDScript diff --git a/getting_started/first_3d_game/05.spawning_mobs.rst b/getting_started/first_3d_game/05.spawning_mobs.rst index 76d001b..a6398ca 100644 --- a/getting_started/first_3d_game/05.spawning_mobs.rst +++ b/getting_started/first_3d_game/05.spawning_mobs.rst @@ -8,10 +8,10 @@ you will have monsters roaming the game board. |image0| -Double-click on ``Main.tscn`` in the *FileSystem* dock to open the *Main* scene. +Double-click on `Main.tscn` in the *FileSystem* dock to open the *Main* scene. Before drawing the path, we're going to change the game resolution. Our game has -a default window size of ``1024x600``. We're going to set it to ``720x540``, a +a default window size of `1024x600`. We're going to set it to `720x540`, a nice little box. Go to *Project -> Project Settings*. @@ -19,7 +19,7 @@ Go to *Project -> Project Settings*. |image1| In the left menu, navigate down to *Display -> Window*. On the right, set the -*Width* to ``720`` and the *Height* to ``540``. +*Width* to `720` and the *Height* to `540`. |image2| @@ -151,7 +151,7 @@ Spawning monsters randomly Right-click on the *Main* node and attach a new script to it. -We first export a variable to the *Inspector* so that we can assign ``Mob.tscn`` +We first export a variable to the *Inspector* so that we can assign `Mob.tscn` or any other monster to it. Then, as we're going to spawn the monsters procedurally, we want to randomize @@ -172,9 +172,9 @@ gdscript GDScript We want to spawn mobs at regular time intervals. To do this, we need to go back to the scene and add a timer. Before that, though, we need to assign the -``Mob.tscn`` file to the ``mob_scene`` property. +`Mob.tscn` file to the `mob_scene` property. -Head back to the 3D screen and select the *Main* node. Drag ``Mob.tscn`` from +Head back to the 3D screen and select the *Main* node. Drag `Mob.tscn` from the *FileSystem* dock to the *Mob Scene* slot in the *Inspector*. |image20| @@ -183,18 +183,18 @@ Add a new *Timer* node as a child of *Main*. Name it *MobTimer*. |image21| -In the *Inspector*, set its *Wait Time* to ``0.5`` seconds and turn on +In the *Inspector*, set its *Wait Time* to `0.5` seconds and turn on *Autostart* so it automatically starts when we run the game. |image22| -Timers emit a ``timeout`` signal every time they reach the end of their *Wait +Timers emit a `timeout` signal every time they reach the end of their *Wait Time*. By default, they restart automatically, emitting the signal in a cycle. We can connect to this signal from the *Main* node to spawn monsters every -``0.5`` seconds. +`0.5` seconds. With the *MobTimer* still selected, head to the *Node* dock on the right and -double-click the ``timeout`` signal. +double-click the `timeout` signal. |image23| @@ -203,14 +203,14 @@ Connect it to the *Main* node. |image24| This will take you back to the script, with a new empty -``_on_MobTimer_timeout()`` function. +`_on_MobTimer_timeout()` function. Let's code the mob spawning logic. We're going to: 1. Instantiate the mob scene. 2. Sample a random position on the spawn path. 3. Get the player's position. -4. Call the mob's ``initialize()`` method, passing it the random position and +4. Call the mob's `initialize()` method, passing it the random position and the player's position. 5. Add the mob as a child of the *Main* node. @@ -232,10 +232,10 @@ gdscript GDScript add_child(mob) ``` -Above, ``randf()`` produces a random value between ``0`` and ``1``, which is -what the *PathFollow* node's ``unit_offset`` expects. +Above, `randf()` produces a random value between `0` and `1`, which is +what the *PathFollow* node's `unit_offset` expects. -Here is the complete ``Main.gd`` script so far, for reference. +Here is the complete `Main.gd` script so far, for reference. gdscript GDScript diff --git a/getting_started/first_3d_game/06.jump_and_squash.rst b/getting_started/first_3d_game/06.jump_and_squash.rst index 7abee6c..2692583 100644 --- a/getting_started/first_3d_game/06.jump_and_squash.rst +++ b/getting_started/first_3d_game/06.jump_and_squash.rst @@ -26,7 +26,7 @@ The important point is that you can use layers and masks to filter physics interactions, control performance, and remove the need for extra conditions in your code. -By default, all physics bodies and areas are set to both layer and mask ``0``. +By default, all physics bodies and areas are set to both layer and mask `0`. This means they all collide with each other. Physics layers are represented by numbers, but we can give them names to keep @@ -73,7 +73,7 @@ see a list of named checkboxes. |image4| -Next up are the *Player* and the *Mob*. Open ``Player.tscn`` by double-clicking +Next up are the *Player* and the *Mob*. Open `Player.tscn` by double-clicking the file in the *FileSystem* dock. Select the *Player* node and set its *Collision -> Mask* to both "enemies" and @@ -82,7 +82,7 @@ Select the *Player* node and set its *Collision -> Mask* to both "enemies" and |image5| -Then, open the *Mob* scene by double-clicking on ``Mob.tscn`` and select the +Then, open the *Mob* scene by double-clicking on `Mob.tscn` and select the *Mob* node. Set its *Collision -> Layer* to "enemies" and unset its *Collision -> Mask*, @@ -104,10 +104,10 @@ Jumping The jumping mechanic itself requires only two lines of code. Open the *Player* script. We need a value to control the jump's strength and update -``_physics_process()`` to code the jump. +`_physics_process()` to code the jump. -After the line that defines ``fall_acceleration``, at the top of the script, add -the ``jump_impulse``. +After the line that defines `fall_acceleration`, at the top of the script, add +the `jump_impulse`. gdscript GDScript @@ -117,8 +117,8 @@ gdscript GDScript export var jump_impulse = 20 ``` -Inside ``_physics_process()``, add the following code before the line where we -called ``move_and_slide()``. +Inside `_physics_process()`, add the following code before the line where we +called `move_and_slide()`. gdscript GDScript @@ -135,8 +135,8 @@ gdscript GDScript That's all you need to jump! -The ``is_on_floor()`` method is a tool from the ``KinematicBody`` class. It -returns ``true`` if the body collided with the floor in this frame. That's why +The `is_on_floor()` method is a tool from the `KinematicBody` class. It +returns `true` if the body collided with the floor in this frame. That's why we apply gravity to the *Player*: so we collide with the floor instead of floating over it like the monsters. @@ -158,7 +158,7 @@ We need to detect collisions with a monster and to differentiate them from collisions with the floor. To do so, we can use Godot's `group ` tagging feature. -Open the scene ``Mob.tscn`` again and select the *Mob* node. Go to the *Node* +Open the scene `Mob.tscn` again and select the *Mob* node. Go to the *Node* dock on the right to see a list of signals. The *Node* dock has two tabs: *Signals*, which you've already used, and *Groups*, which allows you to assign tags to nodes. @@ -181,7 +181,7 @@ Coding the squash mechanic Head back to the *Player* script to code the squash and bounce. -At the top of the script, we need another property, ``bounce_impulse``. When +At the top of the script, we need another property, `bounce_impulse`. When squashing an enemy, we don't necessarily want the character to go as high up as when jumping. @@ -193,8 +193,8 @@ gdscript GDScript export var bounce_impulse = 16 ``` -Then, at the bottom of ``_physics_process()``, add the following loop. With -``move_and_slide()``, Godot makes the body move sometimes multiple times in a +Then, at the bottom of `_physics_process()`, add the following loop. With +`move_and_slide()`, Godot makes the body move sometimes multiple times in a row to smooth out the character's motion. So we have to loop over all collisions that may have happened. @@ -223,34 +223,34 @@ gdscript GDScript That's a lot of new functions. Here's some more information about them. -The functions ``get_slide_count()`` and ``get_slide_collision()`` both come from +The functions `get_slide_count()` and `get_slide_collision()` both come from the `KinematicBody` class and are related to -``move_and_slide()``. +`move_and_slide()`. -``get_slide_collision()`` returns a +`get_slide_collision()` returns a `KinematicCollision` object that holds 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")``. +`collider` property to check if we collided with a "mob" by calling +`is_in_group()` on it: `collision.collider.is_in_group("mob")`. .. note:: - The method ``is_in_group()`` is available on every `Node`. + The method `is_in_group()` is available on every `Node`. To check that we are landing on the monster, we use the vector dot product: -``Vector3.UP.dot(collision.normal) > 0.1``. The collision normal is a 3D vector +`Vector3.UP.dot(collision.normal) > 0.1`. The collision normal is a 3D vector that is perpendicular to the plane where the collision occurred. The dot product allows us to compare it to the up direction. -With dot products, when the result is greater than ``0``, the two vectors are at -an angle of fewer than 90 degrees. A value higher than ``0.1`` tells us that we +With dot products, when the result is greater than `0`, the two vectors are at +an angle of fewer than 90 degrees. A value higher than `0.1` tells us that we are roughly above the monster. -We are calling one undefined function, ``mob.squash()``. We have to add it to +We are calling one undefined function, `mob.squash()`. We have to add it to the Mob class. -Open the script ``Mob.gd`` by double-clicking on it in the *FileSystem* dock. At -the top of the script, we want to define a new signal named ``squashed``. And at +Open the script `Mob.gd` by double-clicking on it in the *FileSystem* dock. At +the top of the script, we want to define a new signal named `squashed`. And at the bottom, you can add the squash function, where we emit the signal and destroy the mob. @@ -271,7 +271,7 @@ gdscript GDScript We will use the signal to add points to the score in the next lesson. With that, you should be able to kill monsters by jumping on them. You can press -:kbd:`F5` to try the game and set ``Main.tscn`` as your project's main scene. +:kbd:`F5` to try the game and set `Main.tscn` as your project's main scene. However, the player won't die yet. We'll work on that in the next part. diff --git a/getting_started/first_3d_game/07.killing_player.rst b/getting_started/first_3d_game/07.killing_player.rst index a21b1bb..4a6b193 100644 --- a/getting_started/first_3d_game/07.killing_player.rst +++ b/getting_started/first_3d_game/07.killing_player.rst @@ -48,17 +48,17 @@ the mask to the "enemies" layer. When areas detect a collision, they emit signals. We're going to connect one to the *Player* node. In the *Node* tab, double-click the -``body_entered`` signal and connect it to the *Player*. +`body_entered` signal and connect it to the *Player*. |image4| -The *MobDetector* will emit ``body_entered`` when a *KinematicBody* or a +The *MobDetector* will emit `body_entered` when a *KinematicBody* or a *RigidBody* node enters it. As it only masks the "enemies" physics layers, it will only detect the *Mob* nodes. Code-wise, we're going to do two things: emit a signal we'll later use to end the game and destroy the player. We can wrap these operations in -a ``die()`` function that helps us put a descriptive label on the code. +a `die()` function that helps us put a descriptive label on the code. gdscript GDScript @@ -88,16 +88,16 @@ and resize them to achieve a tight game feel. Ending the game --------------- -We can use the *Player*\ 's ``hit`` signal to end the game. All we need +We can use the *Player*\ 's `hit` signal to end the game. All we need to do is connect it to the *Main* node and stop the *MobTimer* in reaction. -Open ``Main.tscn``, select the *Player* node, and in the *Node* dock, -connect its ``hit`` signal to the *Main* node. +Open `Main.tscn`, select the *Player* node, and in the *Node* dock, +connect its `hit` signal to the *Main* node. |image5| -Get and stop the timer in the ``_on_Player_hit()`` function. +Get and stop the timer in the `_on_Player_hit()` function. gdscript GDScript @@ -122,7 +122,7 @@ Code checkpoint Here are the complete scripts for the *Main*, *Mob*, and *Player* nodes, for reference. You can use them to compare and check your code. -Starting with ``Main.gd``. +Starting with `Main.gd`. gdscript GDScript @@ -157,7 +157,7 @@ gdscript GDScript $MobTimer.stop() ``` -Next is ``Mob.gd``. +Next is `Mob.gd`. gdscript GDScript @@ -197,7 +197,7 @@ gdscript GDScript queue_free() ``` -Finally, the longest script, ``Player.gd``. +Finally, the longest script, `Player.gd`. gdscript GDScript diff --git a/getting_started/first_3d_game/08.score_and_replay.rst b/getting_started/first_3d_game/08.score_and_replay.rst index a8037dc..f54f686 100644 --- a/getting_started/first_3d_game/08.score_and_replay.rst +++ b/getting_started/first_3d_game/08.score_and_replay.rst @@ -75,16 +75,16 @@ you will see an empty *Font Data* field. This one expects a font file like the ones you have on your computer. DynamicFont supports the following formats: -- TrueType (``.ttf``) -- OpenType (``.otf``) -- Web Open Font Format 1 (``.woff``) -- Web Open Font Format 2 (``.woff2``, since Godot 3.5) +- TrueType (`.ttf`) +- OpenType (`.otf`) +- Web Open Font Format 1 (`.woff`) +- Web Open Font Format 2 (`.woff2`, since Godot 3.5) -In the *FileSystem* dock, expand the ``fonts`` directory and click and drag the -``Montserrat-Medium.ttf`` file we included in the project onto the *Font Data*. +In the *FileSystem* dock, expand the `fonts` directory and click and drag the +`Montserrat-Medium.ttf` file we included in the project onto the *Font Data*. The text will reappear in the theme preview. -The text is a bit small. Set the *Settings -> Size* to ``22`` pixels to increase +The text is a bit small. Set the *Settings -> Size* to `22` pixels to increase the text's size. |image9| @@ -93,7 +93,7 @@ Keeping track of the score -------------------------- Let's work on the score next. Attach a new script to the *ScoreLabel* and define -the ``score`` variable. +the `score` variable. gdscript GDScript @@ -103,22 +103,22 @@ gdscript GDScript var score = 0 ``` -The score should increase by ``1`` every time we squash a monster. We can use -their ``squashed`` signal to know when that happens. However, as we instantiate +The score should increase by `1` every time we squash a monster. We can use +their `squashed` signal to know when that happens. However, as we instantiate monsters from the code, we cannot do the connection in the editor. Instead, we have to make the connection from the code every time we spawn a monster. -Open the script ``Main.gd``. If it's still open, you can click on its name in +Open the script `Main.gd`. If it's still open, you can click on its name in the script editor's left column. |image10| -Alternatively, you can double-click the ``Main.gd`` file in the *FileSystem* +Alternatively, you can double-click the `Main.gd` file in the *FileSystem* dock. -At the bottom of the ``_on_MobTimer_timeout()`` function, add the following +At the bottom of the `_on_MobTimer_timeout()` function, add the following line. gdscript GDScript @@ -130,10 +130,10 @@ gdscript GDScript mob.connect("squashed", $UserInterface/ScoreLabel, "_on_Mob_squashed") ``` -This line means that when the mob emits the ``squashed`` signal, the -*ScoreLabel* node will receive it and call the function ``_on_Mob_squashed()``. +This line means that when the mob emits the `squashed` signal, the +*ScoreLabel* node will receive it and call the function `_on_Mob_squashed()`. -Head back to the ``ScoreLabel.gd`` script to define the ``_on_Mob_squashed()`` +Head back to the `ScoreLabel.gd` script to define the `_on_Mob_squashed()` callback function. There, we increment the score and update the displayed text. @@ -146,9 +146,9 @@ gdscript GDScript text = "Score: %s" % score ``` -The second line uses the value of the ``score`` variable to replace the -placeholder ``%s``. When using this feature, Godot automatically converts values -to text, which is convenient to output text in labels or using the ``print()`` +The second line uses the value of the `score` variable to replace the +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:: @@ -223,8 +223,8 @@ Coding the retry option We can now head to the code to show and hide the *Retry* node when the player dies and plays again. -Open the script ``Main.gd``. First, we want to hide the overlay at the start of -the game. Add this line to the ``_ready()`` function. +Open the script `Main.gd`. First, we want to hide the overlay at the start of +the game. Add this line to the `_ready()` function. gdscript GDScript @@ -247,9 +247,9 @@ gdscript GDScript Finally, when the *Retry* node is visible, we need to listen to the player's input and restart the game if they press enter. To do this, we use the built-in -``_unhandled_input()`` callback. +`_unhandled_input()` callback. -If the player pressed the predefined ``ui_accept`` input action and *Retry* is +If the player pressed the predefined `ui_accept` input action and *Retry* is visible, we reload the current scene. gdscript GDScript @@ -261,7 +261,7 @@ gdscript GDScript get_tree().reload_current_scene() ``` -The function ``get_tree()`` gives us access to the global `SceneTree +The function `get_tree()` gives us access to the global `SceneTree ` object, which allows us to reload and restart the current scene. @@ -289,20 +289,20 @@ Click the *Other Node* button to create an *AudioStreamPlayer* and rename it to |image19| -We included a music soundtrack in the ``art/`` directory, ``House In a Forest -Loop.ogg``. Click and drag it onto the *Stream* property in the *Inspector*. +We included a music soundtrack in the `art/` directory, `House In a Forest +Loop.ogg`. Click and drag it onto the *Stream* property in the *Inspector*. Also, turn on *Autoplay* so the music plays automatically at the start of the game. |image20| -Save the scene as ``MusicPlayer.tscn``. +Save the scene as `MusicPlayer.tscn`. We have to register it as an autoload. Head to the *Project -> Project Settings…* menu and click on the *Autoload* tab. In the *Path* field, you want to enter the path to your scene. Click the folder -icon to open the file browser and double-click on ``MusicPlayer.tscn``. Then, +icon to open the file browser and double-click on `MusicPlayer.tscn`. Then, click the *Add* button on the right to register the node. |image21| @@ -328,7 +328,7 @@ game's viewport. And that does it for this lesson. In the next part, we'll add an animation to make the game both look and feel much nicer. -Here is the complete ``Main.gd`` script for reference. +Here is the complete `Main.gd` script for reference. gdscript GDScript diff --git a/getting_started/first_3d_game/09.adding_animations.rst b/getting_started/first_3d_game/09.adding_animations.rst index acddec6..6324faf 100644 --- a/getting_started/first_3d_game/09.adding_animations.rst +++ b/getting_started/first_3d_game/09.adding_animations.rst @@ -54,7 +54,7 @@ nodes. |image6| -Set the animation duration to ``1.2`` seconds in the top-right of the dock. +Set the animation duration to `1.2` seconds in the top-right of the dock. |image7| @@ -90,17 +90,17 @@ Two tracks appear in the editor with a diamond icon representing each keyframe. |image11| You can click and drag on the diamonds to move them in time. Move the -translation key to ``0.2`` seconds and the rotation key to ``0.1`` seconds. +translation key to `0.2` seconds and the rotation key to `0.1` seconds. |image12| -Move the time cursor to ``0.5`` seconds by clicking and dragging on the gray +Move the time cursor to `0.5` seconds by clicking and dragging on the gray timeline. In the *Inspector*, set the *Translation*'s *Y* axis to about -``0.65`` meters and the *Rotation Degrees*' *X* axis to ``8``. +`0.65` meters and the *Rotation Degrees*' *X* axis to `8`. |image13| -Create a keyframe for both properties and shift the translation key to ``0.7`` +Create a keyframe for both properties and shift the translation key to `0.7` seconds by dragging it on the timeline. |image14| @@ -113,8 +113,8 @@ seconds by dragging it on the timeline. principles. You want to offset and contrast in your character's motion to make them feel alive. -Move the time cursor to the end of the animation, at ``1.2`` seconds. Set the Y -translation to about ``0.35`` and the X rotation to ``-9`` degrees. Once again, +Move the time cursor to the end of the animation, at `1.2` seconds. Set the Y +translation to about `0.35` and the X rotation to `-9` degrees. Once again, create a key for both properties. You can preview the result by clicking the play button or pressing :kbd:`Shift + D`. @@ -183,7 +183,7 @@ Open the *Player*'s script by clicking the script icon next to it. |image22| -In ``_physics_process()``, after the line where we check the ``direction`` +In `_physics_process()`, after the line where we check the `direction` vector, add the following code. gdscript GDScript @@ -199,11 +199,11 @@ gdscript GDScript ``` This code makes it so when the player moves, we multiply the playback speed by -``4``. When they stop, we reset it to normal. +`4`. When they stop, we reset it to normal. We mentioned that the pivot could layer transforms on top of the animation. We can make the character arc when jumping using the following line of code. Add it -at the end of ``_physics_process()``. +at the end of `_physics_process()`. gdscript GDScript @@ -223,12 +223,12 @@ For example, both the *Mob* and the *Player* scenes have a *Pivot* and a *Character* node, so we can reuse animations between them. Open the *Player* scene, select the animation player node and open the "float" animation. -Next, click on **Animation > Copy**. Then open ``Mob.tscn`` and open its animation +Next, click on **Animation > Copy**. Then open `Mob.tscn` and open its animation player. Click **Animation > Paste**. That's it; all monsters will now play the float animation. -We can change the playback speed based on the creature's ``random_speed``. Open -the *Mob*'s script and at the end of the ``initialize()`` function, add the +We can change the playback speed based on the creature's `random_speed`. Open +the *Mob*'s script and at the end of the `initialize()` function, add the following line. gdscript GDScript @@ -244,8 +244,8 @@ And with that, you finished coding your first complete 3D game. **Congratulations**! In the next part, we'll quickly recap what you learned and give you some links -to keep learning more. But for now, here are the complete ``Player.gd`` and -``Mob.gd`` so you can check your code against them. +to keep learning more. But for now, here are the complete `Player.gd` and +`Mob.gd` so you can check your code against them. Here's the *Player* script. diff --git a/getting_started/introduction/godot_design_philosophy.rst b/getting_started/introduction/godot_design_philosophy.rst index 50c83be..fdfe0fd 100644 --- a/getting_started/introduction/godot_design_philosophy.rst +++ b/getting_started/introduction/godot_design_philosophy.rst @@ -164,7 +164,7 @@ or run game code in the editor. This means you can **use the same code** and scenes for your games, or **build plugins and extend the editor.** This leads to a reliable and flexible UI system, as it powers the editor -itself. With the ``tool`` keyword, you can run any game code in the editor. +itself. With the `tool` keyword, you can run any game code in the editor. |image5| @@ -172,7 +172,7 @@ itself. With the ``tool`` keyword, you can run any game code in the editor. UI tools for its node-based programming system and for the rest of the interface.* -Put the ``tool`` keyword at the top of any GDScript file and it will run +Put the `tool` keyword at the top of any GDScript file and it will run 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. @@ -181,7 +181,7 @@ you use in your projects. 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 - ``project.godot`` file. + `project.godot` file. Separate 2D and 3D engines -------------------------- diff --git a/getting_started/introduction/key_concepts_overview.rst b/getting_started/introduction/key_concepts_overview.rst index fbc407d..191e559 100644 --- a/getting_started/introduction/key_concepts_overview.rst +++ b/getting_started/introduction/key_concepts_overview.rst @@ -40,8 +40,8 @@ nodes. .. image:: img/key_concepts_character_nodes.png -It is made of a ``KinematicBody2D`` node named "Character", a ``Sprite``, a -``Camera2D``, and a ``CollisionShape2D``. +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 counterpart have names that end with "3D". diff --git a/getting_started/step_by_step/instancing.rst b/getting_started/step_by_step/instancing.rst index adf544f..d35d91d 100644 --- a/getting_started/step_by_step/instancing.rst +++ b/getting_started/step_by_step/instancing.rst @@ -9,7 +9,7 @@ into any number of scenes. This feature helps you break down and organize your game's different components. You can create as many scenes as you'd like and save them as files with the -``.tscn`` extension, which stands for "text scene". The ``Label.tscn`` file from +`.tscn` extension, which stands for "text scene". The `Label.tscn` file from the previous lesson was an example. We call those files "Packed Scenes" as they pack information about your scene's content. @@ -31,7 +31,7 @@ editor hides their content by default. When you instance the Ball, you only see the Ball node. Notice also how each duplicate has a unique name. Every instance of the Ball scene starts with the same structure and properties -as ``Ball.tscn``. However, you can modify each independently, such as changing +as `Ball.tscn`. However, you can modify each independently, such as changing how they bounce, how heavy they are, or any property exposed by the source scene. @@ -52,7 +52,7 @@ you extracted. .. image:: img/instancing_import_browse.png -Double-click the ``project.godot`` file to open it. +Double-click the `project.godot` file to open it. .. image:: img/instancing_import_project_file.png @@ -60,8 +60,8 @@ Finally, click the Import & Edit button. .. image:: img/instancing_import_and_edit_button.png -The project contains two packed scenes: ``Main.tscn``, containing walls against -which the ball collides, and ``Ball.tscn``. The Main scene should open +The project contains two packed scenes: `Main.tscn`, containing walls against +which the ball collides, and `Ball.tscn`. The Main scene should open automatically. .. image:: img/instancing_main_scene.png @@ -107,19 +107,19 @@ There is more to instances. With this feature, you can: 1. Change the properties of one ball without affecting the others using the Inspector. -2. Change the default properties of every Ball by opening the ``Ball.tscn`` scene +2. Change the default properties of every Ball by opening the `Ball.tscn` scene 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 corresponding packed scene. -Let's try this. Open ``Ball.tscn`` and select the Ball node. In the Inspector on +Let's try this. Open `Ball.tscn` and select the Ball node. In the Inspector on the right, click on the PhysicsMaterial property to expand it. .. image:: img/instancing_physics_material_expand.png -Set its Bounce property to ``2`` by clicking on the number field, typing ``2``, +Set its Bounce property to `2` by clicking on the number field, typing `2`, and pressing :kbd:`Enter`. .. image:: img/instancing_property_bounce_updated.png @@ -134,7 +134,7 @@ on the corresponding tab above the viewport. .. image:: img/instancing_scene_tabs.png Select one of the instanced Ball nodes and, in the Inspector, set its Gravity -Scale value to ``10``. +Scale value to `10`. .. image:: img/instancing_property_gravity_scale.png @@ -149,8 +149,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 - will affect all the others. This is because ``PhysicsMaterial`` is a +.. 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 and click Make Unique in the contextual menu. diff --git a/getting_started/step_by_step/nodes_and_scenes.rst b/getting_started/step_by_step/nodes_and_scenes.rst index 6ba9026..c940ef3 100644 --- a/getting_started/step_by_step/nodes_and_scenes.rst +++ b/getting_started/step_by_step/nodes_and_scenes.rst @@ -144,7 +144,7 @@ button to save it as "Label.tscn". .. image:: img/nodes_and_scenes_11_save_scene_as.png .. 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 + 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 Godot, see `doc_filesystem`. diff --git a/getting_started/step_by_step/scripting_first_script.rst b/getting_started/step_by_step/scripting_first_script.rst index 9696ddb..b5ba307 100644 --- a/getting_started/step_by_step/scripting_first_script.rst +++ b/getting_started/step_by_step/scripting_first_script.rst @@ -55,7 +55,7 @@ Your Scene tab should now only have a Sprite node. A Sprite node needs a texture to display. In the Inspector on the right, you can see that the Texture property says "[empty]". To display the Godot icon, click -and drag the file ``icon.png`` from the FileSystem dock onto the Texture slot. +and drag the file `icon.png` from the FileSystem dock onto the Texture slot. .. image:: img/scripting_first_script_setting_texture.png @@ -86,7 +86,7 @@ other options by default and click the Create button to create the script. .. image:: img/scripting_first_script_attach_node_script.png -The Script workspace should appear with your new ``Sprite.gd`` file open and the +The Script workspace should appear with your new `Sprite.gd` file open and the following line of code: gdscript GDScript @@ -95,18 +95,18 @@ gdscript GDScript extends Sprite ``` -Every GDScript file is implicitly a class. The ``extends`` keyword defines the -class this script inherits or extends. In this case, it's ``Sprite``, meaning +Every GDScript file is implicitly a class. The `extends` keyword defines the +class this script inherits or extends. In this case, it's `Sprite`, meaning our script will get access to all the properties and functions of the Sprite -node, including classes it extends, like ``Node2D``, ``CanvasItem``, and -``Node``. +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``. +our node's `texture`. .. note:: @@ -133,13 +133,13 @@ gdscript GDScript ``` -Let's break it down. The ``func`` keyword defines a new function named -``_init``. This is a special name for our class's constructor. The engine calls -``_init()`` on every object or node upon creating it in memory, if you define +Let's break it down. The `func` keyword defines a new function named +`_init`. This is a special name for our class's constructor. The engine calls +`_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 - that says ``print()`` is necessary for the code to work. If you omit + 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". @@ -149,8 +149,8 @@ It should display "Hello, world!". .. image:: img/scripting_first_script_print_hello_world.png -Delete the ``_init()`` function, so you're only left with the line ``extends -Sprite``. +Delete the `_init()` function, so you're only left with the line `extends +Sprite`. Turning around -------------- @@ -168,17 +168,17 @@ gdscript GDScript Member variables sit near the top of the script, after any "extends" lines, but before functions. Every node -instance with this script attached to it will have its own copy of the ``speed`` -and ``angular_speed`` properties. +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, but you have built-in functions and properties available if you prefer to calculate angles in degrees instead. To move our icon, we need to update its position and rotation every frame in the -game loop. We can use the ``_process()`` virtual function of the ``Node`` class. +game loop. We can use the `_process()` virtual function of the `Node` class. 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 +will call the function every frame and pass it an argument named `delta`, the time elapsed since the last frame. .. note:: @@ -203,23 +203,23 @@ gdscript GDScript rotation += angular_speed * delta ``` -The ``func`` keyword defines a new function. After it, we have to write the +The `func` keyword defines a new function. After it, we have to write the 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. -The line inside the function, ``rotation += angular_speed * delta``, increments -our sprite's rotation every frame. Here, ``rotation`` is a property inherited -from the class ``Node2D``, which ``Sprite`` extends. It controls the rotation of +The line inside the function, `rotation += angular_speed * delta`, increments +our sprite's rotation every frame. Here, `rotation` is a property inherited +from the class `Node2D`, which `Sprite` extends. It controls the rotation of our node and works with radians. .. tip:: In the code editor, you can ctrl-click on any built-in property or - function like ``position``, ``rotation``, or ``_process`` to open the + function like `position`, `rotation`, or `_process` to open the corresponding documentation in a new tab. Run the scene to see the Godot icon turn in-place. @@ -229,7 +229,7 @@ Run the scene to see the Godot icon turn in-place. Moving forward ~~~~~~~~~~~~~~ -Let's now make the node move. Add the following two lines to the ``_process()`` +Let's now make the node move. Add the following two lines to the `_process()` function, ensuring the new lines are indented the same way as the one before them. @@ -241,18 +241,18 @@ gdscript GDScript position += velocity * delta ``` -As we already saw, the ``var`` keyword defines a new variable. If you put it at +As we already saw, the `var` keyword defines a new variable. If you put it at the top of the script, it defines a property of the class. Inside a function, it defines a local variable: it only exists within the function's scope. -We define a local variable named ``velocity``, a 2D vector representing both a +We define a local variable named `velocity`, a 2D vector representing both a direction and a speed. To make the node move forward, we start from the Vector2 class's constant Vector2.UP, a vector pointing up, and rotate it by calling the -``Vector2.rotated()`` method. This expression, ``Vector2.UP.rotated(rotation)``, -is a vector pointing forward relative to our icon. Multiplied by our ``speed`` +`Vector2.rotated()` method. This expression, `Vector2.UP.rotated(rotation)`, +is a vector pointing forward relative to our icon. Multiplied by our `speed` property, it gives us a velocity we can use to move the node forward. -We add ``velocity * delta`` to the node's ``position`` to move it. The position +We add `velocity * delta` to the node's `position` to move it. The position itself is of type `Vector2`, a built-in type in Godot representing a 2D vector. @@ -270,7 +270,7 @@ Our node currently moves by itself. In the next part Complete script --------------- -Here is the complete ``Sprite.gd`` file for reference. +Here is the complete `Sprite.gd` file for reference. gdscript GDScript diff --git a/getting_started/step_by_step/scripting_player_input.rst b/getting_started/step_by_step/scripting_player_input.rst index ecd35b8..83f1fd9 100644 --- a/getting_started/step_by_step/scripting_player_input.rst +++ b/getting_started/step_by_step/scripting_player_input.rst @@ -9,26 +9,26 @@ Listening to player input Building upon the previous lesson `doc_scripting_first_script`, let's look at another important feature of any game: giving control to the player. -To add this, we need to modify our ``Sprite.gd`` code. +To add this, we need to modify our `Sprite.gd` code. .. image:: img/scripting_first_script_moving_with_input.gif You have two main tools to process the player's input in Godot: -1. The built-in input callbacks, mainly ``_unhandled_input()``. Like - ``_process()``, it's a built-in virtual function that Godot calls every time +1. The built-in input callbacks, mainly `_unhandled_input()`. Like + `_process()`, it's a built-in virtual function that Godot calls every time the player presses a key. It's the tool you want to use to react to events that don't happen every frame, like pressing :kbd:`Space` to jump. To learn more about input callbacks, see `doc_inputevent`. -2. The ``Input`` singleton. A singleton is a globally accessible object. Godot +2. The `Input` singleton. A singleton is a globally accessible object. Godot provides access to several in scripts. It's the right tool to check for input every frame. -We're going to use the ``Input`` singleton here as we need to know if the player +We're going to use the `Input` singleton here as we need to know if the player wants to turn or move every frame. -For turning, we should use a new variable: ``direction``. In our ``_process()`` -function, replace the ``rotation += angular_speed * delta`` line with the +For turning, we should use a new variable: `direction`. In our `_process()` +function, replace the `rotation += angular_speed * delta` line with the code below. gdscript GDScript @@ -43,18 +43,18 @@ gdscript GDScript rotation += angular_speed * direction * delta ``` -Our ``direction`` local variable is a multiplier representing the direction in -which the player wants to turn. A value of ``0`` means the player isn't pressing -the left or the right arrow key. A value of ``1`` means the player wants to turn -right, and ``-1`` means they want to turn left. +Our `direction` local variable is a multiplier representing the direction in +which the player wants to turn. A value of `0` means the player isn't pressing +the left or the right arrow key. A value of `1` means the player wants to turn +right, and `-1` means they want to turn left. -To produce these values, we introduce conditions and the use of ``Input``. A -condition starts with the ``if`` keyword in GDScript and ends with a colon. The +To produce these values, we introduce conditions and the use of `Input`. A +condition starts with the `if` keyword in GDScript and ends with a colon. The condition is the expression between the keyword and the end of the line. -To check if a key was pressed this frame, we call ``Input.is_action_pressed()``. -The method takes a text string representing an input action and returns ``true`` -if the action is pressed, ``false`` otherwise. +To check if a key was pressed this frame, we call `Input.is_action_pressed()`. +The method takes a text string representing an input action and returns `true` +if the action is pressed, `false` otherwise. 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 @@ -63,8 +63,8 @@ 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 -> Project Settings and clicking on the Input Map tab. -Finally, we use the ``direction`` as a multiplier when we update the node's -``rotation``: ``rotation += angular_speed * direction * delta``. +Finally, we use the `direction` as a multiplier when we update the node's +`rotation`: `rotation += angular_speed * direction * delta`. If you run the scene with this code, the icon should rotate when you press :kbd:`Left` and :kbd:`Right`. @@ -73,7 +73,7 @@ Moving when pressing "up" ------------------------- To only move when pressing a key, we need to modify the code that calculates the -velocity. Replace the line starting with ``var velocity`` with the code below. +velocity. Replace the line starting with `var velocity` with the code below. gdscript GDScript @@ -83,8 +83,8 @@ gdscript GDScript velocity = Vector2.UP.rotated(rotation) * speed ``` -We initialize the ``velocity`` with a value of ``Vector2.ZERO``, another -constant of the built-in ``Vector`` type representing a 2D vector of length 0. +We initialize the `velocity` with a value of `Vector2.ZERO`, another +constant of the built-in `Vector` type representing a 2D vector of length 0. If the player presses the "ui_up" action, we then update the velocity's value, causing the sprite to move forward. @@ -92,7 +92,7 @@ causing the sprite to move forward. Complete script --------------- -Here is the complete ``Sprite.gd`` file for reference. +Here is the complete `Sprite.gd` file for reference. gdscript GDScript @@ -129,7 +129,7 @@ Summary In summary, every script in Godot represents a class and extends one of the engine's built-in classes. The node types your classes inherit from give you -access to properties like ``rotation`` and ``position`` in our sprite's case. +access to properties like `rotation` and `position` in our sprite's case. You also inherit many functions, which we didn't get to use in this example. In GDScript, the variables you put at the top of the file are your class's @@ -137,12 +137,12 @@ properties, also called member variables. Besides variables, you can define functions, which, for the most part, will be your classes' methods. Godot provides several virtual functions you can define to connect your class -with the engine. These include ``_process()``, to apply changes to the node -every frame, and ``_unhandled_input()``, to receive input events like key and +with the engine. These include `_process()`, to apply changes to the node +every frame, and `_unhandled_input()`, to receive input events like key and button presses from the users. There are quite a few more. -The ``Input`` singleton allows you to react to the players' input anywhere in -your code. In particular, you'll get to use it in the ``_process()`` loop. +The `Input` singleton allows you to react to the players' input anywhere in +your code. In particular, you'll get to use it in the `_process()` loop. In the next lesson `doc_signals`, we'll build upon the relationship between scripts and nodes by having our nodes trigger code in scripts. diff --git a/getting_started/step_by_step/signals.rst b/getting_started/step_by_step/signals.rst index 6befed0..aafae33 100644 --- a/getting_started/step_by_step/signals.rst +++ b/getting_started/step_by_step/signals.rst @@ -38,7 +38,7 @@ Scene setup ----------- To add a button to our game, we will create a new "main" scene which will -include both a button and the ``Sprite.tscn`` scene that we scripted in previous +include both a button and the `Sprite.tscn` scene that we scripted in previous lessons. Create a new scene by going to the menu Scene -> New Scene. @@ -50,7 +50,7 @@ root. .. image:: img/signals_02_2d_scene.png -In the FileSystem dock, click and drag the ``Sprite.tscn`` file you saved +In the FileSystem dock, click and drag the `Sprite.tscn` file you saved previously onto the Node2D to instantiate it. .. image:: img/signals_03_dragging_scene.png @@ -137,14 +137,14 @@ connection. This feature is only available when connecting nodes in the editor. .. image:: img/signals_14_signals_connection_info.png -Let's replace the line with the ``pass`` keyword with code that'll toggle the +Let's replace the line with the `pass` keyword with code that'll toggle the node's motion. -Our Sprite moves thanks to code in the ``_process()`` function. Godot provides a +Our Sprite moves thanks to code in the `_process()` function. Godot provides a method to toggle processing on and off: `Node.set_process() `. Another method of the Node class, -``is_processing()``, returns ``true`` if idle processing is active. We can use -the ``not`` keyword to invert the value. +`is_processing()`, returns `true` if idle processing is active. We can use +the `not` keyword to invert the value. gdscript GDScript @@ -156,7 +156,7 @@ gdscript GDScript This function will toggle processing and, in turn, the icon's motion on and off upon pressing the button. -Before trying the game, we need to simplify our ``_process()`` function to move +Before trying the game, we need to simplify our `_process()` function to move the node automatically and not wait for user input. Replace it with the following code, which we saw two lessons ago: @@ -169,7 +169,7 @@ gdscript GDScript position += velocity * delta ``` -Your complete ``Sprite.gd`` code should look like the following. +Your complete `Sprite.gd` code should look like the following. gdscript GDScript @@ -222,9 +222,9 @@ Click the script icon next to Sprite to jump back to the scripting workspace. 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. +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. @@ -243,13 +243,13 @@ gdscript GDScript var timer = get_node("Timer") ``` -The function ``get_node()`` looks at the Sprite's children and gets nodes by +The function `get_node()` looks at the Sprite's children and gets nodes by their name. For example, if you renamed the Timer node to "BlinkingTimer" in the -editor, you would have to change the call to ``get_node("BlinkingTimer")``. +editor, you would have to change the call to `get_node("BlinkingTimer")`. .. add seealso to a page that explains node features. -We can now connect the Timer to the Sprite in the ``_ready()`` function. +We can now connect the Timer to the Sprite in the `_ready()` function. gdscript GDScript @@ -260,7 +260,7 @@ gdscript GDScript ``` The line reads like so: we connect the Timer's "timeout" signal to the node to -which the script is attached (``self``). When the Timer emits "timeout", we want +which the script is attached (`self`). When the Timer emits "timeout", we want to call the function "_on_Timer_timeout", that we need to define. Let's add it at the bottom of our script and use it to toggle our sprite's visibility. @@ -271,9 +271,9 @@ gdscript GDScript visible = not visible ``` -The ``visible`` property is a boolean that controls the visibility of our node. -The line ``visible = not visible`` toggles the value. If ``visible`` is -``true``, it becomes ``false``, and vice-versa. +The `visible` property is a boolean that controls the visibility of our node. +The line `visible = not visible` toggles the value. If `visible` is +`true`, it becomes `false`, and vice-versa. If you run the scene now, you will see that the sprite blinks on and off, at one second intervals. @@ -282,7 +282,7 @@ Complete script --------------- That's it for our little moving and blinking Godot icon demo! -Here is the complete ``Sprite.gd`` file for reference. +Here is the complete `Sprite.gd` file for reference. gdscript GDScript @@ -341,7 +341,7 @@ you can connect to them like any other. .. image:: img/signals_17_custom_signal.png -To emit a signal in your scripts, call ``emit_signal()``. +To emit a signal in your scripts, call `emit_signal()`. gdscript GDScript @@ -371,7 +371,7 @@ gdscript GDScript correct values. To emit values along with the signal, add them as extra arguments to the -``emit_signal()`` function: +`emit_signal()` function: gdscript GDScript @@ -394,7 +394,7 @@ the game world, to a collision, to a character entering or leaving an area, to an element of the interface changing size, and much more. For example, an `Area2D` representing a coin emits a -``body_entered`` signal whenever the player's physics body enters its collision +`body_entered` signal whenever the player's physics body enters its collision shape, allowing you to know when the player collected it. In the next section, `doc_your_first_2d_game`, you'll create a complete 2D diff --git a/index.rst b/index.rst index 36cfb14..12c9e79 100644 --- a/index.rst +++ b/index.rst @@ -40,7 +40,7 @@ in the top left corner. You can also `download an HTML copy `__ for offline reading (updated every Monday). Extract the ZIP archive then open -the top-level ``index.html`` in a web browser. +the top-level `index.html` in a web browser. .. note:: Godot Engine is an open source project developed by a community of volunteers. The documentation team can always use your @@ -54,7 +54,7 @@ the top-level ``index.html`` in a web browser. help us `translate the documentation `_ into your language, or talk to us on the - ``#documentation`` channel on the `Godot Contributors Chat + `#documentation` channel on the `Godot Contributors Chat `_! .. centered:: |weblate_widget| diff --git a/tutorials/2d/2d_lights_and_shadows.rst b/tutorials/2d/2d_lights_and_shadows.rst index aea4be1..4ecee0f 100644 --- a/tutorials/2d/2d_lights_and_shadows.rst +++ b/tutorials/2d/2d_lights_and_shadows.rst @@ -72,16 +72,16 @@ blending to add the color of their texture to the scene. .. image:: img/light_shadow_light.png -`Lights` have four ``Modes``: ``Add``, ``Sub``, ``Mix``, and ``Mask``. +`Lights` have four `Modes`: `Add`, `Sub`, `Mix`, and `Mask`. -``Add`` adds the color of the light texture to the scene. It brightens the area under the light. +`Add` adds the color of the light texture to the scene. It brightens the area under the light. -``Sub`` subtracts the color of the light from the scene. It darkens the area under the light. +`Sub` subtracts the color of the light from the scene. It darkens the area under the light. -``Mix`` mixes the color of the light with the underlying scene. The resulting brightness is +`Mix` mixes the color of the light with the underlying scene. The resulting brightness is halfway between the color of the light and the color underneath. -``Mask`` is used to mask out areas that are covered by the light. Masked out areas are hidden or revealed based on +`Mask` is used to mask out areas that are covered by the light. Masked out areas are hidden or revealed based on the color of the light. For the demo the lights have two components, the `Light` itself (which @@ -97,7 +97,7 @@ Shadows Shadows are made by intersecting a `Light`. By default shadows are turned off. To turn them on click on the `Light` -and under the Shadows section check ``Enabled``. +and under the Shadows section check `Enabled`. In the demo we are using a `Sprite` with a Texture on it to make the "Shadow Casters", but in reality all you need is a couple of `LightOccluder2Ds`. By itself @@ -116,7 +116,7 @@ background you choose. For this style of shadow it is most likely to be a floor .. image:: img/light_shadow_background.png Next create three `Light2D's`_. You can alter their -color in the top section. By default shadows are turned off and the ``mode`` is set to ``add``. This +color in the top section. By default shadows are turned off and the `mode` is set to `add`. This means that each light adds its own color to whatever is underneath. .. image:: img/light_shadow_all_lights_no_blob.png @@ -137,7 +137,7 @@ Right now the scene should look too bright. This is because all three lights are This is why the demo uses a `CanvasModulate` in the scene. The `CanvasModulate` multiples the entire viewport by a specific color. -Add a `CanvasModulate` to the scene and set its color to ``rgb(70, 70, 70)``. +Add a `CanvasModulate` to the scene and set its color to `rgb(70, 70, 70)`. This will make the scene sufficiently dark to see the effects of the lights distinctly. .. image:: img/light_shadow_ambient.png @@ -159,42 +159,42 @@ the shadow: a wall, a magical chest, or anything else. `LightOccluder2Ds` tell the game what shape the occluder has. They hold an `OccluderPolygon2D`, which is a container for a polygon and some other information. For this demo, since our wall is a square, we -set ``Polygon`` to a square. The other default settings are fine. +set `Polygon` to a square. The other default settings are fine. -The first setting, ``Closed`` can be either ``on`` or ``off``. A closed polygon occludes light +The first setting, `Closed` can be either `on` or `off`. A closed polygon occludes light coming from all directions. An open polygon only occludes light from one direction. -``Cull Mode`` lets you select which direction gets culled. The default is ``Disabled``, meaning the occluder -will cast a shadow no matter which side the light is on. The other two settings ``Clockwise`` and -``Counter-Clockwise`` refer to the winding order of the vertices of the polygon. The winding order +`Cull Mode` lets you select which direction gets culled. The default is `Disabled`, meaning the occluder +will cast a shadow no matter which side the light is on. The other two settings `Clockwise` and +`Counter-Clockwise` refer to the winding order of the vertices of the polygon. The winding order is used to determine which side of the line is inside the polygon. Only outward facing lines cast shadows. -To illustrate the difference, here is an image of a `LightOccluder2D` with ``Closed`` -set to ``off`` in the corresponding `OccluderPolygon2D`, so that the +To illustrate the difference, here is an image of a `LightOccluder2D` with `Closed` +set to `off` in the corresponding `OccluderPolygon2D`, so that the lines of the polygon can be seen: .. image:: 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. .. image:: 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. .. image:: img/light_shadow_cull_counter_clockwise.png -.. 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 +.. 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. When you have added the `LightOccluder2Ds` the shadows still won't appear. You need to go back into the `Light2Ds` and under the Shadow -section set ``Enable`` to ``on``. This turns on shadows with hard edges like in the image below. +section set `Enable` to `on`. This turns on shadows with hard edges like in the image below. .. image:: img/light_shadow_filter0_pcf0.png -To give the shadows that nice, soft edge look we set the variables ``filter``, ``filter smooth``, and -``gradient length``. Godot supports `Percentage Closer Filtering `_ +To give the shadows that nice, soft edge look we set the variables `filter`, `filter smooth`, and +`gradient length`. Godot supports `Percentage Closer Filtering `_ (PCF), which takes multiple samples of the shadow map around a pixel and blurs them to create a smooth shadow effect. The higher the number of samples the smoother the shadow will look, but the slower it will run. That is why Godot provides 3-13 samples by default and allows you to choose. @@ -202,42 +202,42 @@ The demo uses PCF7. .. image:: img/light_shadow_normal.png -.. 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``. +.. 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`. .. image:: img/light_shadow_pcf13.png -.. 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``. +.. 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. +In order to make use of filtering you need to set the `filter smooth` variable. This dictates how far apart the samples are. If you want the soft area to extend quite far, you can increase -the size of ``filter smooth``. However, with few samples and a large filter smooth, you can see lines +the size of `filter smooth`. However, with few samples and a large filter smooth, you can see lines forming between the samples. .. image:: 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. .. image:: 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 +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 a smooth gradient to begin the shadow to reduce the effect of the hard edge. .. image:: img/light_shadow_grad0.png -.. note:: ``gradient length`` is set to ``0``. +.. note:: `gradient length` is set to `0`. .. image:: 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`` +for everyone, which is why Godot provides so much flexibility. Just keep in mind that the higher `filter` set the more expensive the shadows will be. diff --git a/tutorials/2d/2d_meshes.rst b/tutorials/2d/2d_meshes.rst index cc2b580..ba042ba 100644 --- a/tutorials/2d/2d_meshes.rst +++ b/tutorials/2d/2d_meshes.rst @@ -8,12 +8,12 @@ Introduction In 3D, meshes are used to display the world. In 2D, they are rare as images are used more often. 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``). +via `Viewport` and `ViewportTexture`). .. seealso:: 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. +You can experiment creating them yourself using `SurfaceTool` from code and displaying them in a `MeshInstance2D` node. Currently, the only way to generate a 2D mesh within the editor is by either importing an OBJ file as a mesh, or converting it from a Sprite. @@ -23,19 +23,19 @@ Optimizing pixels drawn This workflow is useful for optimizing 2D drawing in some situations. When drawing large images with transparency, Godot will draw the whole quad to the screen. The large transparent areas will still be drawn. This can affect performance, especially on mobile devices, when drawing very large images (generally screen sized), -or layering multiple images on top of each other with large transparent areas (for example, when using ``ParallaxBackground``). +or layering multiple images on top of each other with large transparent areas (for example, when using `ParallaxBackground`). Converting to a mesh will ensure that only the opaque parts will be drawn and the rest will be ignored. Converting Sprites to 2D meshes ------------------------------- -You can take advantage of this optimization by converting a ``Sprite`` to a ``MeshInstance2D``. +You can take advantage of this optimization by converting a `Sprite` to a `MeshInstance2D`. Start with an image that contains large amounts of transparency on the edges, like this tree: .. image:: img/mesh2d1.png -Put it in a ``Sprite`` and select "Convert to 2D Mesh" from the menu: +Put it in a `Sprite` and select "Convert to 2D Mesh" from the menu: .. image:: img/mesh2d2.png @@ -47,6 +47,6 @@ The default values are good enough for many cases, but you can change growth and .. image:: img/mesh2d4.png -Finally, push the ``Convert 2D Mesh`` button and your Sprite will be replaced: +Finally, push the `Convert 2D Mesh` button and your Sprite will be replaced: .. image:: img/mesh2d5.png diff --git a/tutorials/2d/2d_movement.rst b/tutorials/2d/2d_movement.rst index 9577907..53d3057 100644 --- a/tutorials/2d/2d_movement.rst +++ b/tutorials/2d/2d_movement.rst @@ -18,11 +18,11 @@ but the principles will apply to other node types (Area2D, RigidBody2D) as well. Setup ----- -Each example below uses the same scene setup. Start with a ``KinematicBody2D`` with two -children: ``Sprite`` and ``CollisionShape2D``. You can use the Godot icon ("icon.png") +Each example below uses the same scene setup. Start with a `KinematicBody2D` with two +children: `Sprite` and `CollisionShape2D`. You can use the Godot icon ("icon.png") for the Sprite's texture or use any other 2D image you have. -Open ``Project -> Project Settings`` and select the "Input Map" tab. Add the following +Open `Project -> Project Settings` and select the "Input Map" tab. Add the following input actions (see `InputEvent ` for details): .. image:: img/movement_inputs.png @@ -64,13 +64,13 @@ gdscript GDScript velocity = move_and_slide(velocity) ``` -In the ``get_input()`` function, we check for the four key events and sum them +In the `get_input()` function, we check for the four key events and sum them up to get the velocity vector. This has the benefit of making two opposite keys cancel each other out, but will also result in diagonal movement being faster due to the two directions being added together. We can prevent that if we *normalize* the velocity, which means we set -its *length* to ``1``, and multiply by the desired speed. +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`. @@ -121,10 +121,10 @@ gdscript GDScript Here we've added two new variables to track our rotation direction and speed. Again, pressing both keys at once will cancel out and result in no rotation. -The rotation is applied directly to the body's ``rotation`` property. +The rotation is applied directly to the body's `rotation` property. -To set the velocity, we use the ``Vector2.rotated()`` method, so that it points -in the same direction as the body. ``rotated()`` is a useful vector function +To set the velocity, we use the `Vector2.rotated()` method, so that it points +in the same direction as the body. `rotated()` is a useful vector function that you can use in many circumstances where you would otherwise need to apply trigonometric functions. @@ -159,7 +159,7 @@ gdscript GDScript velocity = move_and_slide(velocity) ``` -Here we're using the `Node2D` ``look_at()`` method to +Here we're using the `Node2D` `look_at()` method to point the player towards a given position. Without this function, you could get the same effect by setting the angle like this: @@ -200,16 +200,16 @@ gdscript GDScript ``` -Note the ``distance_to()`` check we make prior to movement. Without this test, +Note the `distance_to()` check we make prior to movement. Without this test, the body would "jitter" upon reaching the target position, as it moves slightly past the position and tries to move back, only to move too far and repeat. -Uncommenting the ``look_at()`` line will also turn the body to point in its +Uncommenting the `look_at()` line will also turn the body to point in its direction of motion if you prefer. .. tip:: This technique can also be used as the basis of a "following" character. - The ``target`` position can be that of any object you want to move to. + The `target` position can be that of any object you want to move to. Summary ------- diff --git a/tutorials/2d/2d_sprite_animation.rst b/tutorials/2d/2d_sprite_animation.rst index f22031f..4e4def1 100644 --- a/tutorials/2d/2d_sprite_animation.rst +++ b/tutorials/2d/2d_sprite_animation.rst @@ -43,7 +43,7 @@ with the following nodes: `Physics Introduction ` for more information. -Now select the ``AnimatedSprite`` and in its *SpriteFrames* property, select +Now select the `AnimatedSprite` and in its *SpriteFrames* property, select "New SpriteFrames". .. image:: img/2d_animation_new_spriteframes.png @@ -70,7 +70,7 @@ Controlling the animation ~~~~~~~~~~~~~~~~~~~~~~~~~ Once the animation is complete, you can control the animation via code using -the ``play()`` and ``stop()`` methods. Here is a brief example to play the +the `play()` and `stop()` methods. Here is a brief example to play the animation while the right arrow key is held, and stop it when the key is released. @@ -92,13 +92,13 @@ gdscript GDScript Sprite sheet with AnimatedSprite -------------------------------- -You can also easily animate from a sprite sheet with the class ``AnimatedSprite``. We will use this public domain sprite sheet: +You can also easily animate from a sprite sheet with the class `AnimatedSprite`. We will use this public domain sprite sheet: .. image:: img/2d_animation_frog_spritesheet.png Right-click the image and choose "Save Image As" to download it, and then copy the image into your project folder. -Set up your scene tree the same way you did previously when using individual images. Select the ``AnimatedSprite`` and in its *SpriteFrames* property, select +Set up your scene tree the same way you did previously when using individual images. Select the `AnimatedSprite` and in its *SpriteFrames* property, select "New SpriteFrames". Click on the new SpriteFrames resource. This time, when the bottom panel appears, select "Add frames from a Sprite Sheet". @@ -152,27 +152,27 @@ setting up your scene tree: Drag the spritesheet into the Sprite's *Texture* property, and you'll see the whole sheet displayed on the screen. To slice it up into individual frames, -expand the *Animation* section in the Inspector and set the *Hframes* to ``6``. +expand the *Animation* section in the Inspector and set the *Hframes* to `6`. *Hframes* and *Vframes* are the number of horizontal and vertical frames in your sprite sheet. .. image:: img/2d_animation_setframes.png Now try changing the value of the *Frame* property. You'll see that it ranges -from ``0`` to ``5`` and the image displayed by the Sprite changes accordingly. +from `0` to `5` and the image displayed by the Sprite changes accordingly. This is the property we'll be animating. -Select the ``AnimationPlayer`` and click the "Animation" button followed by -"New". Name the new animation "walk". Set the animation length to ``0.6`` and +Select the `AnimationPlayer` and click the "Animation" button followed by +"New". Name the new animation "walk". Set the animation length to `0.6` and click the "Loop" button so that our animation will repeat. .. image:: img/2d_animation_new_animation.png -Now select the ``Sprite`` node and click the key icon to add a new track. +Now select the `Sprite` node and click the key icon to add a new track. .. image:: img/2d_animation_new_track.png -Continue adding frames at each point in the timeline (``0.1`` seconds by +Continue adding frames at each point in the timeline (`0.1` seconds by default), until you have all the frames from 0 to 5. You'll see the frames actually appearing in the animation track: @@ -186,7 +186,7 @@ Controlling an AnimationPlayer animation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Like with AnimatedSprite, you can control the animation via code using -the ``play()`` and ``stop()`` methods. Again, here is an example to play the +the `play()` and `stop()` methods. Again, here is an example to play the animation while the right arrow key is held, and stop it when the key is released. @@ -205,19 +205,19 @@ gdscript GDScript ``` .. 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`` + (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. + it's important to keep in mind that `play()` isn't applied instantly. Instead, it's applied the next time the `AnimationPlayer` is processed. This may end up being on the next frame, causing a 'glitch' frame, where the property change was applied but the animation was not. - If this turns out to be a problem, after calling ``play()``, you can call ``advance(0)`` + If this turns out to be a problem, after calling `play()`, you can call `advance(0)` to update the animation immediately. Summary ------- These examples illustrate the two classes you can use in Godot for -2D animation. ``AnimationPlayer`` is -a bit more complex than ``AnimatedSprite``, but it provides additional functionality, since you can also -animate other properties like position or scale. The class ``AnimationPlayer`` can also be used with an ``AnimatedSprite``. Experiment to see what works best for your needs. +2D animation. `AnimationPlayer` is +a bit more complex than `AnimatedSprite`, but it provides additional functionality, since you can also +animate other properties like position or scale. The class `AnimationPlayer` can also be used with an `AnimatedSprite`. Experiment to see what works best for your needs. diff --git a/tutorials/2d/2d_transforms.rst b/tutorials/2d/2d_transforms.rst index 6ef6429..c0f6dba 100644 --- a/tutorials/2d/2d_transforms.rst +++ b/tutorials/2d/2d_transforms.rst @@ -80,7 +80,7 @@ gdscript GDScript Keep in mind, however, that it is generally not desired to work with screen coordinates. The recommended approach is to simply work in Canvas -coordinates (``CanvasItem.get_global_transform()``), to allow automatic +coordinates (`CanvasItem.get_global_transform()`), to allow automatic screen resolution resizing to work properly. Feeding custom input events diff --git a/tutorials/2d/custom_drawing_in_2d.rst b/tutorials/2d/custom_drawing_in_2d.rst index 2f298ad..1b80a44 100644 --- a/tutorials/2d/custom_drawing_in_2d.rst +++ b/tutorials/2d/custom_drawing_in_2d.rst @@ -32,7 +32,7 @@ Drawing Add a script to any `CanvasItem` derived node, like `Control` or -`Node2D`. Then override the ``_draw()`` function. +`Node2D`. Then override the `_draw()` function. gdscript GDScript @@ -50,12 +50,12 @@ class reference. There are plenty of them. Updating -------- -The ``_draw()`` function is only called once, and then the draw commands +The `_draw()` function is only called once, and then the draw commands are cached and remembered, so further calls are unnecessary. If re-drawing is required because a state or something else changed, call `CanvasItem.update()` -in that same node and a new ``_draw()`` call will happen. +in that same node and a new `_draw()` call will happen. Here is a little more complex example, a texture variable that will be redrawn if modified: @@ -78,7 +78,7 @@ gdscript GDScript ``` In some cases, it may be desired to draw every frame. For this, just -call ``update()`` from the ``_process()`` callback, like this: +call `update()` from the `_process()` callback, like this: gdscript GDScript @@ -99,7 +99,7 @@ An example: drawing circular arcs We will now use the custom drawing functionality of the Godot Engine to draw something that Godot doesn't provide functions for. As an example, Godot provides -a ``draw_circle()`` function that draws a whole circle. However, what about drawing a +a `draw_circle()` function that draws a whole circle. However, what about drawing a portion of a circle? You will have to code a function to perform this and draw it yourself. Arc function @@ -135,8 +135,8 @@ gdscript GDScript Remember the number of points our shape has to be decomposed into? We fixed this -number in the ``nb_points`` variable to a value of ``32``. Then, we initialize an empty -``PoolVector2Array``, which is simply an array of ``Vector2``\ s. +number in the `nb_points` variable to a value of `32`. Then, we initialize an empty +`PoolVector2Array`, which is simply an array of `Vector2`\ s. The next step consists of computing the actual positions of these 32 points that compose an arc. This is done in the first for-loop: we iterate over the number of @@ -145,17 +145,17 @@ We first determine the angle of each point, between the starting and ending angl The reason why each angle is decreased by 90° is that we will compute 2D positions out of each angle using trigonometry (you know, cosine and sine stuff...). However, -to be simple, ``cos()`` and ``sin()`` use radians, not degrees. The angle of 0° (0 radian) +to be simple, `cos()` and `sin()` use radians, not degrees. The angle of 0° (0 radian) starts at 3 o'clock, although we want to start counting at 12 o'clock. So we decrease each angle by 90° in order to start counting from 12 o'clock. -The actual position of a point located on a circle at angle ``angle`` (in radians) -is given by ``Vector2(cos(angle), sin(angle))``. Since ``cos()`` and ``sin()`` return values +The actual position of a point located on a circle at angle `angle` (in radians) +is given by `Vector2(cos(angle), sin(angle))`. Since `cos()` and `sin()` return values between -1 and 1, the position is located on a circle of radius 1. To have this -position on our support circle, which has a radius of ``radius``, we simply need to -multiply the position by ``radius``. Finally, we need to position our support circle -at the ``center`` position, which is performed by adding it to our ``Vector2`` value. -Finally, we insert the point in the ``PoolVector2Array`` which was previously defined. +position on our support circle, which has a radius of `radius`, we simply need to +multiply the position by `radius`. Finally, we need to position our support circle +at the `center` position, which is performed by adding it to our `Vector2` value. +Finally, we insert the point in the `PoolVector2Array` which was previously defined. Now, we need to actually draw our points. As you can imagine, we will not simply draw our 32 points: we need to draw everything that is between each of them. @@ -170,7 +170,7 @@ Draw the arc on the screen ^^^^^^^^^^^^^^^^^^^^^^^^^^ We now have a function that draws stuff on the screen; -it is time to call it inside the ``_draw()`` function: +it is time to call it inside the `_draw()` function: gdscript GDScript @@ -223,7 +223,7 @@ constant or else the rotation speed will change accordingly. First, we have to make both angle_from and angle_to variables global at the top of our script. Also note that you can store them in other nodes and access them -using ``get_node()``. +using `get_node()`. gdscript GDScript @@ -238,14 +238,14 @@ gdscript GDScript We make these values change in the _process(delta) function. We also increment our angle_from and angle_to values here. However, we must not -forget to ``wrap()`` the resulting values between 0 and 360°! That is, if the angle +forget to `wrap()` the resulting values between 0 and 360°! That is, if the angle is 361°, then it is actually 1°. If you don't wrap these values, the script will work correctly, but the angle values will grow bigger and bigger over time until -they reach the maximum integer value Godot can manage (``2^31 - 1``). +they reach the maximum integer value Godot can manage (`2^31 - 1`). When this happens, Godot may crash or produce unexpected behavior. -Finally, we must not forget to call the ``update()`` function, which automatically -calls ``_draw()``. This way, you can control when you want to refresh the frame. +Finally, we must not forget to call the `update()` function, which automatically +calls `_draw()`. This way, you can control when you want to refresh the frame. gdscript GDScript @@ -261,7 +261,7 @@ gdscript GDScript update() ``` -Also, don't forget to modify the ``_draw()`` function to make use of these variables: +Also, don't forget to modify the `_draw()` function to make use of these variables: gdscript GDScript @@ -279,14 +279,14 @@ It works, but the arc is rotating insanely fast! What's wrong? The reason is that your GPU is actually displaying the frames as fast as it can. We need to "normalize" the drawing by this speed; to achieve that, we have to make -use of the ``delta`` parameter of the ``_process()`` function. ``delta`` contains the +use of the `delta` parameter of the `_process()` function. `delta` contains the time elapsed between the two last rendered frames. It is generally small -(about 0.0003 seconds, but this depends on your hardware), so using ``delta`` to +(about 0.0003 seconds, but this depends on your hardware), so using `delta` to control your drawing ensures that your program runs at the same speed on everybody's hardware. -In our case, we simply need to multiply our ``rotation_angle`` variable by ``delta`` -in the ``_process()`` function. This way, our 2 angles will be increased by a much +In our case, we simply need to multiply our `rotation_angle` variable by `delta` +in the `_process()` function. This way, our 2 angles will be increased by a much smaller value, which directly depends on the rendering speed. gdscript GDScript @@ -311,13 +311,13 @@ Antialiased drawing Godot offers method parameters in `draw_line` to enable antialiasing, but it doesn't work reliably in all situations (for instance, on mobile/web platforms, or when HDR is enabled). -There is also no ``antialiased`` parameter available in +There is also no `antialiased` parameter available in `draw_polygon`. As a workaround, install and use the `Antialiased Line2D add-on `__ (which also supports antialiased Polygon2D drawing). Note that this add-on relies -on high-level nodes, rather than low-level ``_draw()`` functions. +on high-level nodes, rather than low-level `_draw()` functions. Tools ----- diff --git a/tutorials/2d/particle_systems_2d.rst b/tutorials/2d/particle_systems_2d.rst index a82c970..f354e4e 100644 --- a/tutorials/2d/particle_systems_2d.rst +++ b/tutorials/2d/particle_systems_2d.rst @@ -41,9 +41,9 @@ is because the node needs a ParticlesMaterial to function. ParticlesMaterial ~~~~~~~~~~~~~~~~~ -To add a process material to your particles node, go to ``Process Material`` in -your inspector panel. Click on the box next to ``Material``, and from the dropdown -menu select ``New ParticlesMaterial``. +To add a process material to your particles node, go to `Process Material` in +your inspector panel. Click on the box next to `Material`, and from the dropdown +menu select `New ParticlesMaterial`. .. image:: img/particles_material.png @@ -96,14 +96,14 @@ actually drawn the first time. Speed Scale ~~~~~~~~~~~ -The speed scale has a default value of ``1`` and is used to adjust the +The speed scale has a default value of `1` and is used to adjust the speed of a particle system. Lowering the value will make the particles slower while increasing the value will make the particles much faster. Explosiveness ~~~~~~~~~~~~~ -If lifetime is ``1`` and there are 10 particles, it means a particle +If lifetime is `1` and there are 10 particles, it means a particle will be emitted every 0.1 seconds. The explosiveness parameter changes this, and forces particles to be emitted all together. Ranges are: @@ -118,8 +118,8 @@ creating explosions or sudden bursts of particles: Randomness ~~~~~~~~~~ -All physics parameters can be randomized. Random values range from ``0`` to -``1``. The formula to randomize a parameter is: +All physics parameters can be randomized. Random values range from `0` to +`1`. The formula to randomize a parameter is: :: @@ -129,7 +129,7 @@ Fixed FPS ~~~~~~~~~ This setting can be used to set the particle system to render at a fixed -FPS. For instance, changing the value to ``2`` will make the particles render +FPS. For instance, changing the value to `2` will make the particles render at 2 frames per second. Note this does not slow down the particle system itself. Fract Delta @@ -146,13 +146,13 @@ Visibility Rect The visibility rectangle controls the visibility of the particles on screen. If this rectangle is outside of the viewport, the engine will not render the particles on screen. -The rectangle's ``W`` and ``H`` properties respectively control its Width and its Height. -The ``X`` and ``Y`` properties control the position of the upper-left +The rectangle's `W` and `H` properties respectively control its Width and its Height. +The `X` and `Y` properties control the position of the upper-left corner of the rectangle, relative to the particle emitter. -You can have Godot generate a Visibility Rect automatically using the toolbar above the 2d view. To do so, select the Particles2D node and Click ``Particles > Generate Visibility Rect``. Godot will simulate the Particles2D node emitting particles for a few seconds and set the rectangle to fit the surface the particles take. +You can have Godot generate a Visibility Rect automatically using the toolbar above the 2d view. To do so, select the Particles2D node and Click `Particles > Generate Visibility Rect`. Godot will simulate the Particles2D node emitting particles for a few seconds and set the rectangle to fit the surface the particles take. -You can control the emit duration with the ``Generation Time (sec)`` option. The maximum value is 25 seconds. If you need more time for your particles to move around, you can temporarily change the ``preprocess`` duration on the Particles2D node. +You can control the emit duration with the `Generation Time (sec)` option. The maximum value is 25 seconds. If you need more time for your particles to move around, you can temporarily change the `preprocess` duration on the Particles2D node. Local Coords ~~~~~~~~~~~~ @@ -171,9 +171,9 @@ node is moved, already emitted particles are not affected: Draw Order ~~~~~~~~~~ -This controls the order in which individual particles are drawn. ``Index`` +This controls the order in which individual particles are drawn. `Index` means particles are drawn according to their emission order (default). -``Lifetime`` means they are drawn in order of remaining lifetime. +`Lifetime` means they are drawn in order of remaining lifetime. ParticlesMaterial settings -------------------------- @@ -182,7 +182,7 @@ Direction ~~~~~~~~~ This is the base direction at which particles emit. The default is -``Vector3(1, 0, 0)`` which makes particles emit to the right. However, +`Vector3(1, 0, 0)` which makes particles emit to the right. However, with the default gravity settings, particles will go straight down. .. image:: img/direction1.png @@ -197,7 +197,7 @@ Spread ~~~~~~ This parameter is the angle in degrees which will be randomly added in -either direction to the base ``Direction``. A spread of ``180`` will emit +either direction to the base `Direction`. A spread of `180` will emit in all directions (+/- 180). For spread to do anything the "Initial Velocity" parameter must be greater than 0. @@ -297,8 +297,8 @@ Used to change the color of the particles being emitted. Hue variation ~~~~~~~~~~~~~ -The ``Variation`` value sets the initial hue variation applied to each -particle. The ``Variation Random`` value controls the hue variation +The `Variation` value sets the initial hue variation applied to each +particle. The `Variation Random` value controls the hue variation randomness ratio. Emission Shapes @@ -339,7 +339,7 @@ Three types of emission masks can be generated from a texture: - Directed Border Pixels: Similar to Border Pixels, but adds extra information to the mask to give particles the ability to emit away - from the borders. Note that an ``Initial Velocity`` will need to + from the borders. Note that an `Initial Velocity` will need to be set in order to utilize this. .. image:: img/emission_mask_directed_border.gif @@ -347,14 +347,14 @@ Three types of emission masks can be generated from a texture: Emission Colors ~~~~~~~~~~~~~~~ -``Capture from Pixel`` will cause the particles to inherit the color of the mask at their spawn points. +`Capture from Pixel` will cause the particles to inherit the color of the mask at their spawn points. -Once you click "OK", the mask will be generated and set to the ParticlesMaterial, under the ``Emission Shape`` section: +Once you click "OK", the mask will be generated and set to the ParticlesMaterial, under the `Emission Shape` section: .. image:: img/emission_shapes4.png 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.rst b/tutorials/2d/using_tilemaps.rst index 84de034..40dc94f 100644 --- a/tutorials/2d/using_tilemaps.rst +++ b/tutorials/2d/using_tilemaps.rst @@ -31,7 +31,7 @@ Create a new project and place the above image in the project folder. When using a tileset, it's important that adjacent tiles match up. Godot's default is to import 2D images using an interpolated "filter" mode, which will result in ugly borders between the tiles. Select the image and click the Import tab. Turn -off ``Filter`` and click "Reimport". See `doc_import_images` for details. +off `Filter` and click "Reimport". See `doc_import_images` for details. TileMap node ------------ @@ -47,22 +47,22 @@ customize your tilemap's behavior: .. image:: img/tilemap_size.png -- ``Cell Size`` +- `Cell Size` This defines the size of the grid. This should match the pixel size - of your tiles. The default value is ``(64, 64)``. + of your tiles. The default value is `(64, 64)`. -- ``YSort`` - This causes tiles to be drawn in order of their ``Y`` position, so that +- `YSort` + This causes tiles to be drawn in order of their `Y` position, so that "lower" tiles are drawn on top of "higher" ones. -- ``Half Offset`` and ``Tile Origin`` +- `Half Offset` and `Tile Origin` These properties affect the position of the tile relative to the grid position. -- ``Quadrant`` +- `Quadrant` Defines the chunk size used for batched drawing. This can negatively affect performance. Don't change it unless you know what you're doing. -- ``Custom Transform`` +- `Custom Transform` Used to alter the tile's shape. Use this if you have non-square tiles. All of these options can be left at their defaults for this demo. @@ -87,7 +87,7 @@ of the editor window: .. image:: img/tilemap_tool.png First, you need to add the texture(s) that you'll use for the tiles. Click the -"Add Texture(s) to TileSet" button and select the ``tilesheet.png`` image. +"Add Texture(s) to TileSet" button and select the `tilesheet.png` image. Next, click "New Single Tile" and drag in the image to select the tile you want. Click the "Enable Snap" button to make it easier to select the entire tile. A @@ -289,15 +289,15 @@ Key (applies to the four templates below): **Template - Top-down wall in 3/4 perspective (thick walls):** -When using this template, set the TileSet subtile size to ``Vector2(64, 88)``. +When using this template, set the TileSet subtile size to `Vector2(64, 88)`. .. image:: img/autotile_template_3x3_minimal_topdown_walls_thick.png **Template - Top-down wall in 3/4 perspective (tall walls):** -When using this template, set the "Snap Options" Step to ``Vector2(64, 184)`` +When using this template, set the "Snap Options" Step to `Vector2(64, 184)` and the "Selected Tile" Texture offset to height minus the cell size. -This means the texture offset should be ``Vector2(0, -120)``: +This means the texture offset should be `Vector2(0, -120)`: .. image:: img/autotile_template_3x3_minimal_topdown_walls_tall.png diff --git a/tutorials/3d/baked_lightmaps.rst b/tutorials/3d/baked_lightmaps.rst index 869391e..81db9e0 100644 --- a/tutorials/3d/baked_lightmaps.rst +++ b/tutorials/3d/baked_lightmaps.rst @@ -17,7 +17,7 @@ can't be modified at all. They also don't provide the scene with reflections, so using `doc_reflection_probes` together with it on interiors (or using a Sky on exteriors) is a requirement to get good quality. -As they are baked, they have fewer problems than ``GIProbe`` regarding light +As they are baked, they have fewer problems than `GIProbe` regarding light bleeding, and indirect light will often look better. The downside is that baking lightmaps takes much longer than baking a GIProbe. While baking a GIProbe can be done in a matter of seconds, baking lightmaps will take several minutes if not @@ -81,7 +81,7 @@ their UV2 maps properly generated. result in inefficient lightmaps. Don't reuse a source mesh at significantly different scales if you are planning to use lightmapping. - Also, the ``*.unwrap_cache`` files should *not* be ignored in version control + Also, the `*.unwrap_cache` files should *not* be ignored in version control as these files guarantee that UV2 reimports are consistent across platforms and engine versions. @@ -145,7 +145,7 @@ Configure bounds Lightmap needs an approximate volume of the area affected because it uses it to transfer light to dynamic objects inside it (more on that later). Just -cover the scene with the volume as you do with ``GIProbe``: +cover the scene with the volume as you do with `GIProbe`: .. image:: img/baked_light_bounds.png @@ -256,11 +256,11 @@ bake before exporting your project. To do so, open **Editor > Editor Settings** and adjust **Editors > 3d > Lightmap Baking Number Of Cpu Threads**. - The default value (``0``) uses all of the system's logical CPU cores. + The default value (`0`) uses all of the system's logical CPU cores. Positive values will specify a number of threads to use, while negative values will subtract from the total number of logical CPU cores in the system. For example, on a system with 8 logical CPU cores, adjusting the setting to - ``-1`` will use 7 CPU threads for lightmap baking. + `-1` will use 7 CPU threads for lightmap baking. Configuring bake ~~~~~~~~~~~~~~~~ @@ -343,8 +343,8 @@ Data - **Light Data**: Contains the light baked data after baking. Textures are saved to disk, but this also contains the capture data for dynamic objects, which can - be heavy. If you are using a scene in ``.tscn`` format, you should save this - resource to an external binary ``.lmbake`` file to avoid bloating the ``.tscn`` + be heavy. If you are using a scene in `.tscn` format, you should save this + resource to an external binary `.lmbake` file to avoid bloating the `.tscn` scene with binary data encoded in Base64. The Light Data resource can be edited to adjust two additional properties: diff --git a/tutorials/3d/csg_tools.rst b/tutorials/3d/csg_tools.rst index 2509f89..800337d 100644 --- a/tutorials/3d/csg_tools.rst +++ b/tutorials/3d/csg_tools.rst @@ -135,14 +135,14 @@ Create a scene with a Spatial node as root node. .. image:: img/csg_overdraw.png -Create a CSGBox and name it ``room``, enable **Invert Faces** and change the +Create a CSGBox and name it `room`, enable **Invert Faces** and change the dimensions of your room. .. image:: img/csg_room.png .. image:: img/csg_room_invert.png -Next, create a CSGCombiner and name it ``desk``. +Next, create a CSGCombiner and name it `desk`. A desk has one surface and 4 legs: @@ -159,7 +159,7 @@ Adjust their placement to resemble a desk. within the combiner. Therefore, CSGCombiners are used to organize CSG nodes. -Create a CSGCombiner and name it ``bed``. +Create a CSGCombiner and name it `bed`. Our bed consists of 3 parts: the bed, the mattress and a pillow. Create a CSGBox and adjust its dimension for the bed. Create another CSGBox and adjust its @@ -167,7 +167,7 @@ dimension for the mattress. .. image:: img/csg_bed_mat.png -We will create another CSGCombiner named ``pillow`` as the child of ``bed``. +We will create another CSGCombiner named `pillow` as the child of `bed`. The scene tree should look like this: .. image:: img/csg_bed_tree.png @@ -177,12 +177,12 @@ Y axis of the spheres and enable **Smooth Faces**. .. image:: img/csg_pillow_smooth.png -Select the ``pillow`` node and switch the mode to **Subtraction**; the combined +Select the `pillow` node and switch the mode to **Subtraction**; the combined spheres will cut a hole into the mattress. .. image:: img/csg_pillow_hole.png -Try to re-parent the ``pillow`` node to the root ``Spatial`` node; the hole will +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. @@ -195,7 +195,7 @@ like this: .. image:: img/csg_bed.png -Create a CSGCombiner and name it ``lamp``. +Create a CSGCombiner and name it `lamp`. A lamp consists of 3 parts: the stand, the pole and the lampshade. Create a CSGCylinder, enable the **Cone** option and make it the stand. Create @@ -218,7 +218,7 @@ Adjust the placement of the 3 parts to make it look like a lamp. .. image:: img/csg_lamp.png -Create a CSGCombiner and name it ``bookshelf``. +Create a CSGCombiner and name it `bookshelf`. We will use 3 CSGBox nodes for the bookshelf. Create a CSGBox and adjust its dimensions; this will be the size of the bookshelf. diff --git a/tutorials/3d/environment_and_post_processing.rst b/tutorials/3d/environment_and_post_processing.rst index 6c80348..cfd64f3 100644 --- a/tutorials/3d/environment_and_post_processing.rst +++ b/tutorials/3d/environment_and_post_processing.rst @@ -46,7 +46,7 @@ Just head to Project Settings -> Rendering -> Environment: .. image:: img/environment_default.png New projects created from the Project Manager come with a default environment -(``default_env.tres``). If one needs to be created, save it to disk before +(`default_env.tres`). If one needs to be created, save it to disk before referencing it here. Environment options @@ -152,7 +152,7 @@ The tone mapping options are: tonemapping operator, but it causes bright lighting to look blown out, with noticeable clipping in the output colors. - **Reinhardt:** Performs a variation on rendered pixels' colors by this - formula: ``color = color / (1 + color)``. This avoids clipping bright + formula: `color = color / (1 + color)`. This avoids clipping bright highlights, but the resulting image can look a bit dull. - **Filmic:** This avoids clipping bright highlights, with a resulting image that usually looks more vivid than Reinhardt. @@ -166,13 +166,13 @@ The tone mapping options are: It's recommended to use ACES Fitted instead of ACES. - **Exposure:** Tone mapping exposure which simulates amount of light received - over time (default: ``1.0``). Higher values result in an overall brighter appearance. + over time (default: `1.0`). Higher values result in an overall brighter appearance. If the scene appears too dark as a result of a tonemapping operator or whitepoint change, try increasing this value slightly. - **White:** Tone mapping whitepoint, which simulates where in the scale white is - located (default: ``1.0``). For photorealistic lighting, recommended values are - between ``6.0`` and ``8.0``. Higher values result in less blown out highlights, + located (default: `1.0`). For photorealistic lighting, recommended values are + between `6.0` and `8.0`. Higher values result in less blown out highlights, but make the scene appear slightly darker as a whole. Auto Exposure (HDR) diff --git a/tutorials/3d/gi_probes.rst b/tutorials/3d/gi_probes.rst index ccdd52c..fd1e5b1 100644 --- a/tutorials/3d/gi_probes.rst +++ b/tutorials/3d/gi_probes.rst @@ -21,27 +21,27 @@ will be used, lights can be added, changed or removed, and this will be updated in real-time. Dynamic objects that move within one of these probes will also receive indirect lighting from the scene automatically. -Just like with ``ReflectionProbe``, ``GIProbe`` can be blended (in a bit more limited +Just like with `ReflectionProbe`, `GIProbe` can be blended (in a bit more limited way), so it is possible to provide full real-time lighting for a stage without having to resort to lightmaps. -The main downsides of ``GIProbe`` are: +The main downsides of `GIProbe` are: - A small amount of light leaking can occur if the level is not carefully designed. This must be artist-tweaked. - Performance requirements are higher than for lightmaps, so it may not run properly in low-end integrated GPUs (may need to reduce resolution). -- Reflections are voxelized, so they don't look as sharp as with ``ReflectionProbe``. However, in exchange they are volumetric, so any room size or shape works for them. Mixing them with Screen Space Reflection also works well. +- Reflections are voxelized, so they don't look as sharp as with `ReflectionProbe`. However, in exchange they are volumetric, so any room size or shape works for them. Mixing them with Screen Space Reflection also works well. - They consume considerably more video memory than Reflection Probes, so they must be used with care in the right subdivision sizes. Setting up ---------- -Just like a ``ReflectionProbe``, simply set up the ``GIProbe`` by wrapping it around +Just like a `ReflectionProbe`, simply set up the `GIProbe` by wrapping it around the geometry that will be affected. .. image:: img/giprobe_wrap.png Afterwards, make sure to enable the **Use In Baked Light** property on the geometry instances -in the inspector. This is required for ``GIProbe`` to recognize objects, +in the inspector. This is required for `GIProbe` to recognize objects, otherwise they will be ignored: .. image:: img/giprobe_bake_property.png @@ -60,7 +60,7 @@ toolbar to begin the pre-baking process: Adding lights ------------- -Unless there are materials with emission, ``GIProbe`` does nothing by default. +Unless there are materials with emission, `GIProbe` does nothing by default. Lights need to be added to the scene to have an effect. The effect of indirect light can be viewed quickly (it is recommended you turn @@ -73,7 +73,7 @@ indirect multiplier to tweak this: .. image:: img/giprobe_light_indirect.png -And, as ``GIProbe`` lighting updates in real-time, this effect is immediate: +And, as `GIProbe` lighting updates in real-time, this effect is immediate: .. image:: img/giprobe_indirect_energy_result.png @@ -86,7 +86,7 @@ Probes or Screen Space Reflections, but fully reflect volumetrically. .. image:: img/giprobe_voxel_reflections.png -``GIProbe``\ s can be easily mixed with Reflection Probes and Screen Space Reflections, +`GIProbe`\ s can be easily mixed with Reflection Probes and Screen Space Reflections, as a full 3-stage fallback-chain. This allows to have precise reflections where needed: .. image:: img/giprobe_ref_blending.png @@ -128,7 +128,7 @@ GI Probes support a few parameters for tweaking: Quality ------- -``GIProbe``\ s are quite demanding. It is possible to use lower quality voxel cone +`GIProbe`\ s are quite demanding. It is possible to use lower quality voxel cone tracing in exchange for more performance. .. image:: img/giprobe_quality.png diff --git a/tutorials/3d/lights_and_shadows.rst b/tutorials/3d/lights_and_shadows.rst index fd317ec..c9bf3bc 100644 --- a/tutorials/3d/lights_and_shadows.rst +++ b/tutorials/3d/lights_and_shadows.rst @@ -38,7 +38,7 @@ Each one has a specific function: - **Bake Mode**: Sets the bake mode for the light. For more information see `doc_baked_lightmaps` - **Cull Mask**: Objects that are in the selected layers below will be affected by this light. Note that objects disabled via this cull mask will still cast shadows. - If you don't want disabled objects to cast shadows, adjust the ``cast_shadow`` property on the + If you don't want disabled objects to cast shadows, adjust the `cast_shadow` property on the GeometryInstance to the desired value. Shadow mapping @@ -76,11 +76,11 @@ although that may lead to decreased performance. The other downside is that materials that have their cull mode set to **Disabled** or MeshInstances with Cast Shadow set to **Double-Sided** may exhibit shadow acne. - - Set **Bias** to ``-0.01``. The bias should be a negative value when + - Set **Bias** to `-0.01`. The bias should be a negative value when **Reverse Cull Face** is enabled, but it should be a positive value when it's disabled. - - For DirectionalLight, set the directional shadow **Normal Bias** to ``0.0`` - and **Bias Split Scale** to ``0.0``. Depending on your scene, you may also - want to further decrease **Bias** to a value between ``-0.05`` and ``-0.1``. + - For DirectionalLight, set the directional shadow **Normal Bias** to `0.0` + and **Bias Split Scale** to `0.0`. Depending on your scene, you may also + want to further decrease **Bias** to a value between `-0.05` and `-0.1`. Following the above tips should make it possible to avoid gaps in shadows without resorting to contact shadows (which have many issues of their own). diff --git a/tutorials/3d/occluders.rst b/tutorials/3d/occluders.rst index 29d79cc..90424f6 100644 --- a/tutorials/3d/occluders.rst +++ b/tutorials/3d/occluders.rst @@ -3,11 +3,11 @@ Occluder Nodes ============== -In addition to occlusion via `doc_rooms_and_portals`, Godot also has the ability to provide basic occlusion using simple geometric ``Occluder`` nodes. These are geometric shapes that are shown in the editor using gizmos, but are invisible at runtime. +In addition to occlusion via `doc_rooms_and_portals`, Godot also has the ability to provide basic occlusion using simple geometric `Occluder` nodes. These are geometric shapes that are shown in the editor using gizmos, but are invisible at runtime. 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. @@ -15,18 +15,18 @@ The reason that Occluder nodes are so cheap in performance terms is that the eng The Occluder node itself is a holder for an OccluderShape resource, which determines the functionality. To get started, add an Occluder node to your scene tree. -.. tip:: You will see a yellow warning triangle that lets you know that you must set an OccluderShape from the inspector before the ``Occluder`` becomes functional. +.. tip:: You will see a yellow warning triangle that lets you know that you must set an OccluderShape from the inspector before the `Occluder` becomes functional. OccluderShapeSphere ------------------- The sphere is one of the simplest and fastest occluders, and is easy to setup and position. The downside is that the sphere only tends to make sense in certain game level designs, and is more suited to terrain or organic background geometry. -Once you have added an OccluderNode and chosen to add a new ``OccluderShapeSphere`` in the inspector, click the OccluderShapeSphere in the inspector to bring up the parameters. +Once you have added an OccluderNode and chosen to add a new `OccluderShapeSphere` in the inspector, click the OccluderShapeSphere in the inspector to bring up the parameters. .. image:: img/occluder_shape_sphere_inspector.png -Unlike many Nodes, the ``OccluderShapeSphere`` can store multiple spheres in the same object. This is more efficient in the engine, and keeps your SceneTree clearer. You don't have to store all your spheres in one Occluder as it could become tricky to manage, but it is perfectly reasonable to add 10 or so spheres or more. They are very cheap, and often the more you place, the better the match you will get to your geometry. +Unlike many Nodes, the `OccluderShapeSphere` can store multiple spheres in the same object. This is more efficient in the engine, and keeps your SceneTree clearer. You don't have to store all your spheres in one Occluder as it could become tricky to manage, but it is perfectly reasonable to add 10 or so spheres or more. They are very cheap, and often the more you place, the better the match you will get to your geometry. In order to store multiple spheres, they are stored as an Array. If you click on the Array in the inspector, you can increase the size of the Array to add one. @@ -47,18 +47,18 @@ OccluderShapePolygon The polygon is a generalist occluder. It can be made to work well in almost all situations, and can quickly provide a degree of occlusion culling to most scenes. -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. +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). Editing and details ~~~~~~~~~~~~~~~~~~~ -Occluder polygons are edited as a list of points which define a *convex* polygon, on a single plane. In order to confine the polygon to a single plane, the points are defined in 2D space rather than 3D. The orientation, position and scale of the polygon is taken instead from the transform of the ``Occluder`` Node. +Occluder polygons are edited as a list of points which define a *convex* polygon, on a single plane. In order to confine the polygon to a single plane, the points are defined in 2D space rather than 3D. The orientation, position and scale of the polygon is taken instead from the transform of the `Occluder` Node. .. image:: img/occluder_shape_polygon_inspector.png -If you create an Occluder and add to it a ``OccluderShapePolygon`` resource, by default it will create 4 starting points forming a rectangle. If you move the position and rotation of the Occluder Node you will see how the rectangle follows the node. When the Occluder is selected in the editor, handles will appear for each of the points. You can actually click and drag these handles, to match your polygon to the environment of your scene. +If you create an Occluder and add to it a `OccluderShapePolygon` resource, by default it will create 4 starting points forming a rectangle. If you move the position and rotation of the Occluder Node you will see how the rectangle follows the node. When the Occluder is selected in the editor, handles will appear for each of the points. You can actually click and drag these handles, to match your polygon to the environment of your scene. .. image:: img/occluder_shape_polygon.png diff --git a/tutorials/3d/portals/advanced_room_and_portal_usage.rst b/tutorials/3d/portals/advanced_room_and_portal_usage.rst index 94f8ddf..2f910b8 100644 --- a/tutorials/3d/portals/advanced_room_and_portal_usage.rst +++ b/tutorials/3d/portals/advanced_room_and_portal_usage.rst @@ -19,7 +19,7 @@ How does a monster know whether it is within the gameplay area? This problem is solved because the portal system contains a subsystem called the **Gameplay Monitor** that can be turned on and off from the `RoomManager`. When switched on, any roaming objects that move inside or outside the gameplay area (whether by moving themselves, or the camera moving) will receive callbacks to let them know of this change. -You can choose to either receive these callbacks as ``signals``, or as ``notifications``. +You can choose to either receive these callbacks as `signals`, or as `notifications`. Notifications can be handled in GDScript or other scripting languages: @@ -32,9 +32,9 @@ Notifications can be handled in GDScript or other scripting languages: NOTIFICATION_EXIT_GAMEPLAY: print("notification exit gameplay") -Signals are sent just as any other signal. They can be attached to functions using the editor inspector. The signals are called ``gameplay_entered`` and ``gameplay_exited``. +Signals are sent just as any other signal. They can be attached to functions using the editor inspector. The signals are called `gameplay_entered` and `gameplay_exited`. -In fact, you don't just receive these callbacks for ``ROAMING`` objects. In addition Rooms and RoomGroups (which can be used to form groups of rooms) can also receive callbacks. For example, you can use this to trigger AI behaviour when the player reaches certain points in a level. +In fact, you don't just receive these callbacks for `ROAMING` objects. In addition Rooms and RoomGroups (which can be used to form groups of rooms) can also receive callbacks. For example, you can use this to trigger AI behaviour when the player reaches certain points in a level. VisbilityNotifiers / VisibilityEnablers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -56,7 +56,7 @@ A `RoomGroup` is a special node which allows you to deal with a .. image:: img/roomgroups.png -For instance, when outside you may wish to use a `DirectionalLight` to represent the sun. When the outside RoomGroup receives an ``enter gameplay`` callback, you can turn the light on, and you can turn it off when the RoomGroup exits gameplay. With the light off, performance will increase as there is no need to render it indoors. +For instance, when outside you may wish to use a `DirectionalLight` to represent the sun. When the outside RoomGroup receives an `enter gameplay` callback, you can turn the light on, and you can turn it off when the RoomGroup exits gameplay. With the light off, performance will increase as there is no need to render it indoors. This is an example of a simple RoomGroup script to turn on and off a DirectionalLight. Note that you can also use signals for callbacks (the choice is up to you): @@ -78,7 +78,7 @@ With the functionality described so far you *can* do it - you would need to plac It turns out there is a simpler way of handling this scenario. Godot supports *rooms **within** rooms* (we will call them **"internal rooms"**). That is, you can place a house within a terrain room, or even a building, or set of buildings, and even have exit portals in different terrain rooms! -To create internal rooms, you don't need to place a room within another room in the scene tree - in fact you will get a warning if you try this. Instead, create them as regular rooms. The internal rooms should be grouped together with a RoomGroup as parent. If you look in the inspector for the RoomGroup, there is a **Room Group Priority** which defaults to ``0``. +To create internal rooms, you don't need to place a room within another room in the scene tree - in fact you will get a warning if you try this. Instead, create them as regular rooms. The internal rooms should be grouped together with a RoomGroup as parent. If you look in the inspector for the RoomGroup, there is a **Room Group Priority** which defaults to `0`. If you want a room or set of rooms to be internal, set the priority to a higher value than the outer (enclosing) room, using the RoomGroup. @@ -88,7 +88,7 @@ The only differences: - Portals between internal rooms and outer rooms should always *be placed in the inner (internal) room*. - Portals of internal rooms are not considered as part of the bound of outer rooms. -- ``STATIC`` and ``DYNAMIC`` objects from outer rooms will not sprawl into internal rooms. If you want objects to cross these portals, place them in the internal room. This is to prevent large objects like terrain sections sprawling into entire buildings, and rendering when not necessary. +- `STATIC` and `DYNAMIC` objects from outer rooms will not sprawl into internal rooms. If you want objects to cross these portals, place them in the internal room. This is to prevent large objects like terrain sections sprawling into entire buildings, and rendering when not necessary. Internal room example ^^^^^^^^^^^^^^^^^^^^^ @@ -116,15 +116,15 @@ We have created a Room node (which will become the internal room) into which we However there is a problem. The naive autoplace algorithm will look at the center of the exterior mesh, and attempt to place it *within* the internal room. We want to avoid this somehow, as the idea of the exterior mesh is to have something rendered from the outside, so it must be in the outer room for everything to work. -To get around this problem, there is a special setting to enable you to express a preference for autoplacing in an outer room. Each object has an **Autoplace Priority** setting. When set to ``0``, there is no preference (the object will be placed in the highest priority room). +To get around this problem, there is a special setting to enable you to express a preference for autoplacing in an outer room. Each object has an **Autoplace Priority** setting. When set to `0`, there is no preference (the object will be placed in the highest priority room). -However, if we set this autoplace priority to ``-1`` for example, the autoplace will always choose a ``-1`` priority room (if one is present at that location). So if we set the outer room priority to ``-1``, it will always place our exterior into our "outside" room. +However, if we set this autoplace priority to `-1` for example, the autoplace will always choose a `-1` priority room (if one is present at that location). So if we set the outer room priority to `-1`, it will always place our exterior into our "outside" room. .. image:: img/autoplace_priority.png 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/editing_rooms_and_portals.rst b/tutorials/3d/portals/editing_rooms_and_portals.rst index 1e47041..f84f76c 100644 --- a/tutorials/3d/portals/editing_rooms_and_portals.rst +++ b/tutorials/3d/portals/editing_rooms_and_portals.rst @@ -9,12 +9,12 @@ Putting all the ideas together, here is an example scene tree: .. image:: img/example_scenetree.png - We have used a `RoomGroup` to denote an outside area. -- The `MeshInstance`\ s inside the `Room`\ s are either ``STATIC`` or ``DYNAMIC``. -- We have created a `Spatial` (I decided to call it 'Freeform', but you could use any name) under which to place ``STATIC`` and ``DYNAMIC`` objects that will be autoplaced in rooms - (Freeform is inside the ``roomlist``, but *not* inside a room.) -- The player and the monsters are on branches *OUTSIDE* the ``roomlist``. -- The player and monster meshes have portal mode ``ROAMING`` so they can be in any room. -- The camera is outside the ``roomlist``. +- The `MeshInstance`\ s inside the `Room`\ s are either `STATIC` or `DYNAMIC`. +- We have created a `Spatial` (I decided to call it 'Freeform', but you could use any name) under which to place `STATIC` and `DYNAMIC` objects that will be autoplaced in rooms + (Freeform is inside the `roomlist`, but *not* inside a room.) +- The player and the monsters are on branches *OUTSIDE* the `roomlist`. +- The player and monster meshes have portal mode `ROAMING` so they can be in any room. +- The camera is outside the `roomlist`. .. _doc_rooms_and_portals_blender: @@ -26,18 +26,18 @@ Although you can create your room system entirely within the editor, you can als Postfix convention ^^^^^^^^^^^^^^^^^^ -- ``-room`` becomes a `Room`. -- ``-roomgroup`` becomes a `RoomGroup`. -- ``-portal`` becomes a `Portal`. -- ``-bound`` becomes a manual bound. +- `-room` becomes a `Room`. +- `-roomgroup` becomes a `RoomGroup`. +- `-portal` becomes a `Portal`. +- `-bound` becomes a manual bound. -Rooms and RoomGroups should be created as Empties within Blender. Any mesh children of the ``-room`` Empty will thus be placed in the Room during conversion in Godot. +Rooms and RoomGroups should be created as Empties within Blender. Any mesh children of the `-room` Empty will thus be placed in the Room during conversion in Godot. For example: -- ``kitchen-room`` - create a Room called "kitchen". -- ``outside-roomgroup`` - create a RoomGroup called "outside". -- ``kitchen-portal`` - create a Portal leading to the "kitchen" Room. +- `kitchen-room` - create a Room called "kitchen". +- `outside-roomgroup` - create a RoomGroup called "outside". +- `kitchen-portal` - create a Portal leading to the "kitchen" Room. Portals ^^^^^^^ @@ -46,20 +46,20 @@ Portals are different from Rooms. In Portals, we need to specify the geometry of Portal meshes have some restrictions to work properly. They must be convex, and the polygon points should be in the same plane. The accuracy to the plane does not have to be exact, as Godot will automatically average the direction of the portal plane. Once converted to a `Portal` node, the snapping to the portal plane is enforced, and the vertices are specified (and editable) as 2D coordinates in the inspector, rather than 3D points. -The portal's naming is quite important. You can either name the portal ``-portal`` which will attempt to autolink the Portal in Godot, or you can use the name of the Room you wish to link the Portal to as a prefix. +The portal's naming is quite important. You can either name the portal `-portal` which will attempt to autolink the Portal in Godot, or you can use the name of the Room you wish to link the Portal to as a prefix. Wildcard ^^^^^^^^ -In most cases, this can be done using a name such as ``kitchen-portal``. However, there is one problem. Blender and Godot do not deal well when you have multiple objects with the same name. What happens when we want more than one Portal to lead to the kitchen? +In most cases, this can be done using a name such as `kitchen-portal`. However, there is one problem. Blender and Godot do not deal well when you have multiple objects with the same name. What happens when we want more than one Portal to lead to the kitchen? -The workaround is the use of a *wildcard* character, ``*``. When Godot reads the wildcard, it will ignore anything placed after it in the name. +The workaround is the use of a *wildcard* character, `*`. When Godot reads the wildcard, it will ignore anything placed after it in the name. This means we can use the following portal names: -- ``kitchen*1-portal`` - creates a Portal leading to the "kitchen". -- ``kitchen*2-portal`` - also creates a Portal leading to the "kitchen". -- ``kitchen*anything_you_want_here-portal`` - also works. +- `kitchen*1-portal` - creates a Portal leading to the "kitchen". +- `kitchen*2-portal` - also creates a Portal leading to the "kitchen". +- `kitchen*anything_you_want_here-portal` - also works. Wildcards work on all of the nodes which use these naming conventions. @@ -68,7 +68,7 @@ Manual bounds Manual bounds are a way of explicitly setting the convex hull for a room, and are used if they are present as children of a room in the scene tree. Aside from the postfix, the naming is unimportant. They should be meshes (i.e. MeshInstance in Godot). Bear in mind they will be converted to convex hulls during the conversion process, so they don't have to be perfect. -.. tip:: Once used during conversion, they will be converted to the ``IGNORE`` **Portal Mode** and won't be shown. You can alternatively use **Generate Points** within the editor to convert these to a set of points stored in the room, and delete the original ``-bound`` MeshInstance. +.. tip:: Once used during conversion, they will be converted to the `IGNORE` **Portal Mode** and won't be shown. You can alternatively use **Generate Points** within the editor to convert these to a set of points stored in the room, and delete the original `-bound` MeshInstance. Portal point editing ~~~~~~~~~~~~~~~~~~~~ @@ -86,7 +86,7 @@ You can edit these points in the gizmo or inspector to make a better match to th Room point editing ~~~~~~~~~~~~~~~~~~ -You also have the option to manually edit the points used to define the convex hull of a room. These points are not present by default. You would typically create them by pressing the **Generate Points** button in the editor toolbar when a room is selected. This will transfer the auto bound from the geometry (or manual ``-bound`` mesh) into the inspector. Once there are points in the inspector, they will be used and override any other method. So if you wish to revert your manual editing, delete all the room's points. +You also have the option to manually edit the points used to define the convex hull of a room. These points are not present by default. You would typically create them by pressing the **Generate Points** button in the editor toolbar when a room is selected. This will transfer the auto bound from the geometry (or manual `-bound` mesh) into the inspector. Once there are points in the inspector, they will be used and override any other method. So if you wish to revert your manual editing, delete all the room's points. .. image:: img/room_point_editing.png @@ -98,7 +98,7 @@ RoomManager Show Debug ^^^^^^^^^^ -This can be used to control the amount of logging, especially the room conversion logs. Debug will always be set to ``false`` on exported projects. +This can be used to control the amount of logging, especially the room conversion logs. Debug will always be set to `false` on exported projects. Debug Sprawl ^^^^^^^^^^^^ @@ -108,12 +108,12 @@ This mode will only display meshes that are sprawling through portals from the c Merge Meshes ^^^^^^^^^^^^ -To keep drawcalls to a minimum, the system offers the option to automatically merge similar ``STATIC`` meshes within a room (also known as *static batching*). This can increase performance in many cases. The culling accuracy is reduced, but as a room is a fairly logical unit for culling, this trade off usually works in your favor. +To keep drawcalls to a minimum, the system offers the option to automatically merge similar `STATIC` meshes within a room (also known as *static batching*). This can increase performance in many cases. The culling accuracy is reduced, but as a room is a fairly logical unit for culling, this trade off usually works in your favor. Plane Simplification ^^^^^^^^^^^^^^^^^^^^ -In some cases, the convex hulls automatically generated for rooms may contain a very large number of planes, particularly if you use curved surfaces. This is not ideal because it slows down the system. This option can optionally simplify hulls. The degree of simplification can be selected by the user, between ``0`` (no simplification) and ``1`` (maximum simplification). You can also override this value in individual rooms. +In some cases, the convex hulls automatically generated for rooms may contain a very large number of planes, particularly if you use curved surfaces. This is not ideal because it slows down the system. This option can optionally simplify hulls. The degree of simplification can be selected by the user, between `0` (no simplification) and `1` (maximum simplification). You can also override this value in individual rooms. Portals ~~~~~~~ @@ -131,7 +131,7 @@ Portals can either be two-way or one-way. The default two-way portals are quicke Particle Systems ~~~~~~~~~~~~~~~~ -Be aware that when placing ``STATIC`` particle systems, the AABB on conversion may have zero size. This means the particle system may be unexpectedly culled early. To prevent this, either set the particle system ``portal mode`` to ``DYNAMIC``, or alternatively, add an **Extra Cull Margin** to the particle system in the Geometry Inspector. +Be aware that when placing `STATIC` particle systems, the AABB on conversion may have zero size. This means the particle system may be unexpectedly culled early. To prevent this, either set the particle system `portal mode` to `DYNAMIC`, or alternatively, add an **Extra Cull Margin** to the particle system in the Geometry Inspector. Multimeshes ~~~~~~~~~~~ diff --git a/tutorials/3d/portals/first_steps_with_rooms_and_portals.rst b/tutorials/3d/portals/first_steps_with_rooms_and_portals.rst index 0273340..a49034c 100644 --- a/tutorials/3d/portals/first_steps_with_rooms_and_portals.rst +++ b/tutorials/3d/portals/first_steps_with_rooms_and_portals.rst @@ -9,7 +9,7 @@ Anytime you want to use the portal system, you need to include a special node in Room Conversion ^^^^^^^^^^^^^^^ -This conversion must take place every time you want to activate the system. It does not store the *room graph* in your project (for flexibility and to save memory). You can either trigger it by pressing the **Convert Rooms** button in the editor toolbar (which also has a keyboard shortcut) or by calling the ``rooms_convert()`` method in the RoomManager. The latter method will be what you use in-game. Note that for safety, best practice is to call ``rooms_clear()`` before unloading or changing levels. +This conversion must take place every time you want to activate the system. It does not store the *room graph* in your project (for flexibility and to save memory). You can either trigger it by pressing the **Convert Rooms** button in the editor toolbar (which also has a keyboard shortcut) or by calling the `rooms_convert()` method in the RoomManager. The latter method will be what you use in-game. Note that for safety, best practice is to call `rooms_clear()` before unloading or changing levels. .. image:: img/convert_rooms_button.png @@ -22,7 +22,7 @@ If you convert the level while the editor is running, the portal culling system The RoomList ^^^^^^^^^^^^ -Before we create any rooms, we must first create a node to be the parent of all the static objects, rooms, roomgroups, and so on in our level. This node is referred to as the the ``RoomList``. +Before we create any rooms, we must first create a node to be the parent of all the static objects, rooms, roomgroups, and so on in our level. This node is referred to as the the `RoomList`. .. image:: img/roomlist_node.png @@ -78,7 +78,7 @@ Because defining the room bound is the most important aspect of the system, ther 1. Use the geometry of the objects contained within the room to automatically create an approximate bound. 2. Manually edit the points that define the convex hull in the room inspector or drag the points around using the editor gizmo (see `doc_room_point_editing`). -3. Provide a manual bound. This is a MeshInstance in the room that has geometry in the shape of the desired bound, with a name with the postfix ``-bound``. This is something you might choose to do if you create your levels in Blender or similar (see `doc_rooms_and_portals_blender`). +3. Provide a manual bound. This is a MeshInstance in the room that has geometry in the shape of the desired bound, with a name with the postfix `-bound`. This is something you might choose to do if you create your levels in Blender or similar (see `doc_rooms_and_portals_blender`). While the first option can be all that is required, particularly with simple rooms or for pre-production, using manual bounds gives you ultimate control at the expense of a small amount of editing. You can also combine the two approaches, perhaps using automatic bounds for most rooms but manually editing problem areas. @@ -93,7 +93,7 @@ Portals If you create some rooms, place objects within them, then convert the level in the editor, you will see the objects in the rooms appearing and showing as you move between rooms. There is one problem, however! Although you can see the objects within the room that the camera is in, you can't see to any neighbouring rooms! For that we need portals. -`Portal`\ s are special convex polygons that you position over the openings between rooms in order to allow the system to see between them. You can create a portal node directly in the editor. The default portal has 4 points and behaves much like a ``plane`` `MeshInstance`. You can add or remove points using the inspector. A portal requires at least 3 points to work - this is because it needs to form a polygon rather than a point or line. +`Portal`\ s are special convex polygons that you position over the openings between rooms in order to allow the system to see between them. You can create a portal node directly in the editor. The default portal has 4 points and behaves much like a `plane` `MeshInstance`. You can add or remove points using the inspector. A portal requires at least 3 points to work - this is because it needs to form a polygon rather than a point or line. To save editing effort, **only one Portal is required between each pair of Rooms**. You *do not need* to (and indeed should not) create two Portals that overlap in opposite directions. Portals default to being two-way, but you can make them one-way in the Portal inspector. diff --git a/tutorials/3d/portals/rooms_and_portals_example.rst b/tutorials/3d/portals/rooms_and_portals_example.rst index 006c5e1..1482a74 100644 --- a/tutorials/3d/portals/rooms_and_portals_example.rst +++ b/tutorials/3d/portals/rooms_and_portals_example.rst @@ -20,7 +20,7 @@ Step 1 - Next add a `RoomManager` node. We will need this later to process the room system. - Next we need to start defining our rooms. We create all our rooms under another Spatial we have called 'RoomList'. - Add a new `Room` node as a child of the roomlist. -- We have named the room ``Kitchen``. +- We have named the room `Kitchen`. - We will now create the geometry of our room. The names you give to the geometry is up to you. - Create a `MeshInstance` for the floor. Create a box by adding a CubeMesh resource to the MeshInstance. Scale and position it to form a floor. - Create MeshInstances for the walls. Create more box meshes for this, then scale and position them. Be sure to leave an opening on one side. You will need to create two wall segments to do this on that side. @@ -31,9 +31,9 @@ Step 2 .. image:: tutorial_simple/img/tutorial_simple_2.png - Now we need to create the other room. -- You can do this simply by duplicating the first room (select the ``Kitchen`` node, right click and choose **Duplicate**). +- You can do this simply by duplicating the first room (select the `Kitchen` node, right click and choose **Duplicate**). - Rotate and position the second room so that the openings line up. -- Rename the second room to ``Lounge``. +- Rename the second room to `Lounge`. Step 3 ~~~~~~ @@ -42,7 +42,7 @@ Step 3 - Next, we will add a portal between the two rooms. - Create a new `Portal` in the kitchen. -- Scale and position the portal using the node ``Transform`` in the inspector, so it fits within the opening between the two rooms. +- Scale and position the portal using the node `Transform` in the inspector, so it fits within the opening between the two rooms. - The portal plane should face *outward* from the source room, i.e. towards the lounge. This direction is indicated by the arrow in the editor gizmo, and portal gizmo's color. Step 4 @@ -52,7 +52,7 @@ Step 4 - To make things more exciting, we want to add a few more boxes to the rooms. - Placing these boxes as children or grandchildren of the room nodes explicitly tells the system which room the objects should be in. However, we can also create these objects *outside* the rooms. Provided they are in the RoomList branch, the system will attempt to automatically place them in the correct room at runtime. -- On the screenshot, the boxes were places as children of a Spatial I have called ``Freeform`` to keep things tidy. +- On the screenshot, the boxes were places as children of a Spatial I have called `Freeform` to keep things tidy. - Boxes also have a green SpatialMaterial assigned to them to make them stand out more from the rest of the room. - Let's also create an `OmniLight` so it will be autoplaced in one of the rooms. @@ -85,10 +85,10 @@ Some things to try ^^^^^^^^^^^^^^^^^^ - Create different types of geometry. CSG nodes, Particle systems, and Multimeshes are all supported by the portal system. -- Try creating a Camera and adding it to the scene. If you run the scene you will notice that the portal culling is not active. This is because the ``room graph`` must be created each time you load a level, by converting the rooms. Instead of using a button in the editor, in real games you call a function in the RoomManager to convert the level, called ``rooms_convert()``. Try this out with a script, perhaps running within a ``_ready()`` function. -- The geometry you created so far is all ``STATIC`` (non-moving). If you look in the inspector for geometry nodes, you will see they derive from ``CullInstance``. Here you can set the **Portal Mode** for objects in the portal system. This determines how the node is processed. -- If you now write a script to move one of your objects within a room and view it through a Camera as the scene runs, you may notice that the object gets culled incorrectly. This is because ``STATIC`` objects are assumed not to move in the system. If you instead change the object to ``DYNAMIC``, it should now update the culling correctly. -- There are several ``portal_modes``, these are described in the main documentation. -- Try turning the portal on and off at runtime from your script. You can call ``set_portal_active()`` to open and close the portal. +- Try creating a Camera and adding it to the scene. If you run the scene you will notice that the portal culling is not active. This is because the `room graph` must be created each time you load a level, by converting the rooms. Instead of using a button in the editor, in real games you call a function in the RoomManager to convert the level, called `rooms_convert()`. Try this out with a script, perhaps running within a `_ready()` function. +- The geometry you created so far is all `STATIC` (non-moving). If you look in the inspector for geometry nodes, you will see they derive from `CullInstance`. Here you can set the **Portal Mode** for objects in the portal system. This determines how the node is processed. +- If you now write a script to move one of your objects within a room and view it through a Camera as the scene runs, you may notice that the object gets culled incorrectly. This is because `STATIC` objects are assumed not to move in the system. If you instead change the object to `DYNAMIC`, it should now update the culling correctly. +- There are several `portal_modes`, these are described in the main documentation. +- Try turning the portal on and off at runtime from your script. You can call `set_portal_active()` to open and close the portal. - If you select the portal, you should see 4 handles appear. Try dragging the portal points with the mouse, and see how it affects the objects that are culled. - If you select a room and click the **Generate Points** button in the toolbar, it will store the points of the room hull in the room inspector. You can now edit these with the gizmo handles. diff --git a/tutorials/3d/portals/using_objects_in_rooms_and_portals.rst b/tutorials/3d/portals/using_objects_in_rooms_and_portals.rst index 50c03a9..a347b45 100644 --- a/tutorials/3d/portals/using_objects_in_rooms_and_portals.rst +++ b/tutorials/3d/portals/using_objects_in_rooms_and_portals.rst @@ -6,14 +6,14 @@ Normally, when you use Godot, all objects that you can see (`VisualInstance`, where you can set a ``PortalMode``. This determines how objects will behave in the portal system. +If you look in the inspector, every VisualInstance in Godot is derived from a `CullInstance`, where you can set a `PortalMode`. This determines how objects will behave in the portal system. .. image:: img/cull_instance.png STATIC ^^^^^^ -The default mode for objects is ``STATIC``. Static objects are objects within rooms that will not move throughout the lifecycle of the level. Things like floors, walls, ceilings are good candidates for ``STATIC`` objects. +The default mode for objects is `STATIC`. Static objects are objects within rooms that will not move throughout the lifecycle of the level. Things like floors, walls, ceilings are good candidates for `STATIC` objects. DYNAMIC ^^^^^^^ @@ -23,48 +23,48 @@ Dynamic mode is for objects that are expected to move during the game. But there ROAMING ^^^^^^^ -Roaming mode is for objects that can move between rooms. Things like players and enemies should be marked as roaming. These are more expensive to calculate than ``STATIC`` or ``DYNAMIC`` modes, because the system has to keep track of which room a roaming object is within. +Roaming mode is for objects that can move between rooms. Things like players and enemies should be marked as roaming. These are more expensive to calculate than `STATIC` or `DYNAMIC` modes, because the system has to keep track of which room a roaming object is within. GLOBAL ^^^^^^ -Global mode is for objects that you don't want occlusion culled at all. Things like a main player's weapon, bullets and some particle effects are good candidates for ``GLOBAL`` mode. +Global mode is for objects that you don't want occlusion culled at all. Things like a main player's weapon, bullets and some particle effects are good candidates for `GLOBAL` mode. IGNORE ^^^^^^ -Ignore is a special mode for objects that will be essentially free in the system. Manual bounds (``-bound``) get converted to ignore portal mode automatically. They don't need to show up during the game, but are kept in the scene tree in case you need to convert the level multiple times (e.g. in the Editor). You might also choose to use this for objects that you *only* want to show up in the editor (when RoomManager is inactive). +Ignore is a special mode for objects that will be essentially free in the system. Manual bounds (`-bound`) get converted to ignore portal mode automatically. They don't need to show up during the game, but are kept in the scene tree in case you need to convert the level multiple times (e.g. in the Editor). You might also choose to use this for objects that you *only* want to show up in the editor (when RoomManager is inactive). Should you place objects within rooms (in the scene tree) or not? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -``STATIC`` and ``DYNAMIC`` objects are ideally placed within rooms in the scene tree. The system needs to know which room they are in during conversion as it assumes they will never change room. Placing them within rooms in the scene tree allows you to explicitly tell the system where you want them. +`STATIC` and `DYNAMIC` objects are ideally placed within rooms in the scene tree. The system needs to know which room they are in during conversion as it assumes they will never change room. Placing them within rooms in the scene tree allows you to explicitly tell the system where you want them. Autoplace ^^^^^^^^^ -However, for ease of use, it is also possible to place ``STATIC`` and ``DYNAMIC`` objects *outside* the rooms in the scene tree, but within the RoomList branch. The system will attempt to **autoplace** the objects into the appropriate room. This works in most cases but if in doubt, use the explicit approach. The explicit approach is especially needed when dealing with internal rooms, which have some restrictions for sprawling objects. +However, for ease of use, it is also possible to place `STATIC` and `DYNAMIC` objects *outside* the rooms in the scene tree, but within the RoomList branch. The system will attempt to **autoplace** the objects into the appropriate room. This works in most cases but if in doubt, use the explicit approach. The explicit approach is especially needed when dealing with internal rooms, which have some restrictions for sprawling objects. .. image:: img/freeform.png -Note that if you place ``STATIC`` and ``DYNAMIC`` objects outside of rooms, they will not contribute to the room bound. If you are using the room geometry to derive the bound, tables and chairs can be placed outside the room. However, walls and floors should be explicitly within the Room's branch of the scene tree to ensure the bound is correct. +Note that if you place `STATIC` and `DYNAMIC` objects outside of rooms, they will not contribute to the room bound. If you are using the room geometry to derive the bound, tables and chairs can be placed outside the room. However, walls and floors should be explicitly within the Room's branch of the scene tree to ensure the bound is correct. -``ROAMING`` and ``GLOBAL`` objects are recommended to be kept in a branch of the scene tree outside of any rooms or the RoomList. They *can* be placed inside the rooms, but to save confusion, they are normally better kept on their own branch. There are no restrictions on the placement of ``IGNORE`` objects. +`ROAMING` and `GLOBAL` objects are recommended to be kept in a branch of the scene tree outside of any rooms or the RoomList. They *can* be placed inside the rooms, but to save confusion, they are normally better kept on their own branch. There are no restrictions on the placement of `IGNORE` objects. Object Lifetimes ^^^^^^^^^^^^^^^^ -It is important to note that the lifetime of ``STATIC`` and ``DYNAMIC`` objects is tied to the lifetime of the level, between when you call ``rooms_convert()`` to activate the portal system, and calling ``rooms_clear()`` to unload the system. This is because quite a bit of pre-processing goes on during the conversion phase in order to render them efficiently. +It is important to note that the lifetime of `STATIC` and `DYNAMIC` objects is tied to the lifetime of the level, between when you call `rooms_convert()` to activate the portal system, and calling `rooms_clear()` to unload the system. This is because quite a bit of pre-processing goes on during the conversion phase in order to render them efficiently. -You should therefore not try to create or delete ``STATIC`` or ``DYNAMIC`` objects while the portal system is active. Doing so will cause the system to automatically unload because it is in an invalid state. You can however, freely ``show()`` and ``hide()`` these objects. +You should therefore not try to create or delete `STATIC` or `DYNAMIC` objects while the portal system is active. Doing so will cause the system to automatically unload because it is in an invalid state. You can however, freely `show()` and `hide()` these objects. The sequence should be therefore: - Load your level. -- Place any ``STATIC`` or ``DYNAMIC`` objects. -- Then run ``rooms_convert()`` *after* all the ``STATIC`` and ``DYNAMIC`` objects were added to the scene tree. +- Place any `STATIC` or `DYNAMIC` objects. +- Then run `rooms_convert()` *after* all the `STATIC` and `DYNAMIC` objects were added to the scene tree. -Objects that are ``ROAMING``, ``GLOBAL`` or ``IGNORE`` can be freely created and deleted as required. +Objects that are `ROAMING`, `GLOBAL` or `IGNORE` can be freely created and deleted as required. Sprawling ~~~~~~~~~ @@ -76,7 +76,7 @@ This means that if the corner of an object extends into a neighbouring room, but Portal Margins ^^^^^^^^^^^^^^ -It is hard to place objects exactly at the edges of rooms, and if we chose to sprawl objects to the adjacent room the moment a portal was crossed (even by a very small amount), there would be an unnecessary amount of sprawling, and objects would end up being rendered when not really required. To counter this, portals have an adjustable ``margin`` over which an object can cross without being considered in the next room. The margin is shown in the editor gizmo as a red translucent area. +It is hard to place objects exactly at the edges of rooms, and if we chose to sprawl objects to the adjacent room the moment a portal was crossed (even by a very small amount), there would be an unnecessary amount of sprawling, and objects would end up being rendered when not really required. To counter this, portals have an adjustable `margin` over which an object can cross without being considered in the next room. The margin is shown in the editor gizmo as a red translucent area. You can set the margin globally in the RoomManager. You can also override this margin value in any portal if you need to finetune things. As you edit the margin values in the inspector, you should see the margins update in the 3D editor viewport. diff --git a/tutorials/3d/procedural_geometry/arraymesh.rst b/tutorials/3d/procedural_geometry/arraymesh.rst index d704352..c6ea083 100644 --- a/tutorials/3d/procedural_geometry/arraymesh.rst +++ b/tutorials/3d/procedural_geometry/arraymesh.rst @@ -8,15 +8,15 @@ This tutorial will present the basics of using an `ArrayMesh`. To do so, we will use the function `add_surface_from_arrays()`, which takes up to four parameters. The first two are required, while the second two are optional. -The first parameter is the ``PrimitiveType``, an OpenGL concept that instructs the GPU +The first parameter is the `PrimitiveType`, an OpenGL concept that instructs the GPU how to arrange the primitive based on the vertices given, i.e. whether they represent triangles, lines, points, etc. See `Mesh.PrimitiveType ` for the options available. -The second parameter, ``arrays``, is the actual Array that stores the mesh information. The array is a -normal Godot array that is constructed with empty brackets ``[]``. It stores a ``Pool**Array`` +The second parameter, `arrays`, is the actual Array that stores the mesh information. The array is a +normal Godot array that is constructed with empty brackets `[]`. It stores a `Pool**Array` (e.g. PoolVector3Array, PoolIntArray, etc.) for each type of information that will be used to build the surface. -The possible elements of ``arrays`` are listed below, together with the position they must have within ``arrays``. +The possible elements of `arrays` are listed below, together with the position they must have within `arrays`. See also `Mesh.ArrayType `. @@ -31,46 +31,46 @@ See also `Mesh.ArrayType `. - Array type * - 0 - - ``ARRAY_VERTEX`` + - `ARRAY_VERTEX` - `PoolVector3Array` * - 1 - - ``ARRAY_NORMAL`` + - `ARRAY_NORMAL` - `PoolVector3Array` * - 2 - - ``ARRAY_TANGENT`` + - `ARRAY_TANGENT` - `PoolRealArray` of groups of 4 floats. First 3 floats determine the tangent, and the last the binormal direction as -1 or 1. * - 3 - - ``ARRAY_COLOR`` + - `ARRAY_COLOR` - `PoolColorArray` * - 4 - - ``ARRAY_TEX_UV`` + - `ARRAY_TEX_UV` - `PoolVector2Array` * - 5 - - ``ARRAY_TEX_UV2`` + - `ARRAY_TEX_UV2` - `PoolVector2Array` * - 6 - - ``ARRAY_BONES`` + - `ARRAY_BONES` - `PoolRealArray` of groups of 4 ints. Each group lists indexes of 4 bones that affects a given vertex. * - 7 - - ``ARRAY_WEIGHTS`` - - `PoolRealArray` of groups of 4 floats. Each float lists the amount of weight an determined bone on ``ARRAY_BONES`` has on a given vertex. + - `ARRAY_WEIGHTS` + - `PoolRealArray` of groups of 4 floats. Each float lists the amount of weight an determined bone on `ARRAY_BONES` has on a given vertex. * - 8 - - ``ARRAY_INDEX`` + - `ARRAY_INDEX` - `PoolIntArray` The array of vertices (at index 0) is always required. The index array is optional and will only be used if included. We won't use it in this tutorial. -All the other arrays carry information about the vertices. They are also optional and will only be used if included. Some of these arrays (e.g. ``ARRAY_COLOR``) -use one entry per vertex to provide extra information about vertices. They must have the same size as the vertex array. Other arrays (e.g. ``ARRAY_TANGENT``) use +All the other arrays carry information about the vertices. They are also optional and will only be used if included. Some of these arrays (e.g. `ARRAY_COLOR`) +use one entry per vertex to provide extra information about vertices. They must have the same size as the vertex array. Other arrays (e.g. `ARRAY_TANGENT`) use four entries to describe a single vertex. These must be exactly four times larger than the vertex array. For normal usage, the last two parameters in `add_surface_from_arrays()` are typically left empty. @@ -84,7 +84,7 @@ from code without creating one. Next, add a script to the MeshInstance. -Under ``_ready()``, create a new Array. +Under `_ready()`, create a new Array. gdscript GDScript @@ -94,7 +94,7 @@ gdscript GDScript This will be the array that we keep our surface information in - it will hold all the arrays of data that the surface needs. Godot will expect it to be of -size ``Mesh.ARRAY_MAX``, so resize it accordingly. +size `Mesh.ARRAY_MAX`, so resize it accordingly. gdscript GDScript @@ -115,7 +115,7 @@ gdscript GDScript ``` Once you have filled your data arrays with your geometry you can create a mesh -by adding each array to ``surface_array`` and then committing to the mesh. +by adding each array to `surface_array` and then committing to the mesh. gdscript GDScript @@ -128,7 +128,7 @@ 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/immediategeometry.rst b/tutorials/3d/procedural_geometry/immediategeometry.rst index 264d3eb..9e2b875 100644 --- a/tutorials/3d/procedural_geometry/immediategeometry.rst +++ b/tutorials/3d/procedural_geometry/immediategeometry.rst @@ -10,18 +10,18 @@ API like SurfaceTool, but it's actually designed to create meshes on the fly. Generating complex geometry (several thousand vertices) with this node is inefficient, even if it's done only once. Instead, it is designed to generate simple geometry that changes every frame. -Before starting, you should clear the geometry by calling ``clear()``. This ensures that +Before starting, you should clear the geometry by calling `clear()`. This ensures that you are not building upon the geometry from the previous frame. If you want to keep geometry between frames, do -not call ``clear()``. +not call `clear()`. -To begin generating geometry you must call ``begin()``. ``begin()`` takes a ``PrimitiveType`` as an argument. -``PrimitiveType`` is an OpenGL concept that instructs the GPU how to arrange the primitive based on the +To begin generating geometry you must call `begin()`. `begin()` takes a `PrimitiveType` as an argument. +`PrimitiveType` is an OpenGL concept that instructs the GPU how to arrange the primitive based on the vertices given whether it is triangles, lines, points, etc. A complete list can be found under the `Mesh` class reference page. -Once you have called ``begin()`` you are ready to start adding vertices. You add vertices one at a time. -First you add vertex specific attributes such as normals or UVs using ``set_****()`` (e.g. ``set_normal()``). -Then you call ``add_vertex()`` to add a vertex with those attributes. For example: +Once you have called `begin()` you are ready to start adding vertices. You add vertices one at a time. +First you add vertex specific attributes such as normals or UVs using `set_****()` (e.g. `set_normal()`). +Then you call `add_vertex()` to add a vertex with those attributes. For example: gdscript GDScript @@ -32,9 +32,9 @@ gdscript GDScript add_vertex(Vector3(0, 0, 1)) ``` -Only attributes added before the call to ``add_vertex()`` will be included in that vertex. +Only attributes added before the call to `add_vertex()` will be included in that vertex. -Finally, once you have added all your vertices call ``end()`` to signal that you have finished generating the mesh. +Finally, once you have added all your vertices call `end()` to signal that you have finished generating the mesh. The example code below draws a single triangle. diff --git a/tutorials/3d/procedural_geometry/index.rst b/tutorials/3d/procedural_geometry/index.rst index 2888a7f..1bb4dc0 100644 --- a/tutorials/3d/procedural_geometry/index.rst +++ b/tutorials/3d/procedural_geometry/index.rst @@ -59,13 +59,13 @@ in the Mesh when you use a MeshInstance using the `material_override` property. Surface array ^^^^^^^^^^^^^ -The surface array is an array of length ``ArrayMesh.ARRAY_MAX``. Each position in the array is +The surface array is an array of length `ArrayMesh.ARRAY_MAX`. Each position in the array is filled with a sub-array containing per-vertex information. For example, the array located at -``ArrayMesh.ARRAY_NORMAL`` is a `PoolVector3Array` of vertex normals. +`ArrayMesh.ARRAY_NORMAL` is a `PoolVector3Array` of vertex normals. See `Mesh.ArrayType ` for more information. The surface array can be indexed or non-indexed. Creating a non-indexed array is as easy as not assigning -an array at the index ``ArrayMesh.ARRAY_INDEX``. A non-indexed array stores unique vertex information for +an array at the index `ArrayMesh.ARRAY_INDEX`. A non-indexed array stores unique vertex information for every triangle, meaning that when two triangles share a vertex, the vertex is duplicated in the array. An indexed surface array only stores vertex information for each unique vertex and then also stores an array of indices which maps out how to construct the triangles from the vertex array. In general, using an indexed @@ -123,7 +123,7 @@ Which approach you use depends on what you are trying to do and what kind of pro Both SurfaceTool and ArrayMesh are excellent for generating static geometry (meshes) that don't change over time. Using an ArrayMesh is slightly faster than using a SurfaceTool, but the API is a little more challenging. -Additionally, SurfaceTool has a few quality of life methods such as ``generate_normals()`` and ``index()``. +Additionally, SurfaceTool has a few quality of life methods such as `generate_normals()` and `index()`. ImmediateGeometry regenerates the mesh every frame, so it is much slower than ArrayMesh or SurfaceTool. However, if you need the geometry to change every frame anyway, it provides a much easier interface that may even be a little faster than generating diff --git a/tutorials/3d/procedural_geometry/meshdatatool.rst b/tutorials/3d/procedural_geometry/meshdatatool.rst index 9dec4a0..f2a945a 100644 --- a/tutorials/3d/procedural_geometry/meshdatatool.rst +++ b/tutorials/3d/procedural_geometry/meshdatatool.rst @@ -11,12 +11,12 @@ 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. +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. -In the examples below, assume an ArrayMesh called ``mesh`` has already been created. See `ArrayMesh tutorial ` for an example of mesh generation. +In the examples below, assume an ArrayMesh called `mesh` has already been created. See `ArrayMesh tutorial ` for an example of mesh generation. gdscript GDScript @@ -25,7 +25,7 @@ gdscript GDScript mdt.create_from_surface(mesh, 0) ``` -``create_from_surface()`` uses the vertex arrays from the ArrayMesh to calculate two additional arrays, +`create_from_surface()` uses the vertex arrays from the ArrayMesh to calculate two additional arrays, one for edges and one for faces, for a total of three arrays. An edge is a connection between any two vertices. Each edge in the edge array contains a reference to @@ -37,7 +37,7 @@ a reference to the three vertices and three edges it is composed of. The vertex array contains edge, face, normal, color, tangent, uv, uv2, bone, and weight information connected with each vertex. -To access information from these arrays you use a function of the form ``get_****()``: +To access information from these arrays you use a function of the form `get_****()`: gdscript GDScript @@ -70,7 +70,7 @@ gdscript GDScript mdt.commit_to_surface(mesh) ``` -Below is a complete example that turns a spherical mesh called ``mesh`` into a randomly deformed blob complete with updated normals and vertex colors. +Below is a complete example that turns a spherical mesh called `mesh` into a randomly deformed blob complete with updated normals and vertex colors. See `ArrayMesh tutorial ` for how to generate the base mesh. gdscript GDScript diff --git a/tutorials/3d/procedural_geometry/surfacetool.rst b/tutorials/3d/procedural_geometry/surfacetool.rst index 62a144d..350eea0 100644 --- a/tutorials/3d/procedural_geometry/surfacetool.rst +++ b/tutorials/3d/procedural_geometry/surfacetool.rst @@ -8,7 +8,7 @@ The interface is similar to the `ImmediateGeometry` node. You set each per-vertex attribute (e.g. normal, uv, color) and then when you add a vertex it captures the attributes. -The SurfaceTool also provides some useful helper functions like ``index()`` and ``generate_normals()``. +The SurfaceTool also provides some useful helper functions like `index()` and `generate_normals()`. Attributes are added before each vertex is added: @@ -23,9 +23,9 @@ gdscript GDScript ``` When finished generating your geometry with the `SurfaceTool` -call ``commit()`` to finish generating the mesh. If an `ArrayMesh` is passed -to ``commit()`` then it appends a new surface to the end of the ArrayMesh. While if nothing is passed -in, ``commit()`` returns an ArrayMesh. +call `commit()` to finish generating the mesh. If an `ArrayMesh` is passed +to `commit()` then it appends a new surface to the end of the ArrayMesh. While if nothing is passed +in, `commit()` returns an ArrayMesh. gdscript GDScript @@ -62,8 +62,8 @@ gdscript GDScript var mesh = st.commit() ``` -You can optionally add an index array, either by calling ``add_index()`` and adding -vertices to the index array or by calling ``index()`` which shrinks the vertex array +You can optionally add an index array, either by calling `add_index()` and adding +vertices to the index array or by calling `index()` which shrinks the vertex array to remove duplicate vertices. gdscript GDScript @@ -84,7 +84,7 @@ gdscript GDScript ``` Similarly, if you have an index array, but you want each vertex to be unique (e.g. because -you want to use unique normals or colors per face instead of per-vertex), you can call ``deindex()``. +you want to use unique normals or colors per face instead of per-vertex), you can call `deindex()`. gdscript GDScript @@ -92,12 +92,12 @@ gdscript GDScript st.deindex() ``` -If you don't add custom normals yourself, you can add them using ``generate_normals()``, which should -be called after generating geometry and before committing the mesh using ``commit()`` or -``commit_to_arrays()``. Calling ``generate_normals(true)`` will flip the resulting normals. As a side -note, ``generate_normals()`` only works if the primitive type is set to ``Mesh.PRIMITIVE_TRIANGLES``. +If you don't add custom normals yourself, you can add them using `generate_normals()`, which should +be called after generating geometry and before committing the mesh using `commit()` or +`commit_to_arrays()`. Calling `generate_normals(true)` will flip the resulting normals. As a side +note, `generate_normals()` only works if the primitive type is set to `Mesh.PRIMITIVE_TRIANGLES`. -If you don't add custom tangents, they can be added with ``generate_tangents()``, but it requires +If you don't add custom tangents, they can be added with `generate_tangents()`, but it requires that each vertex have UVs and normals set already. gdscript GDScript @@ -108,6 +108,6 @@ gdscript GDScript ``` By default, when generating normals, they will be calculated on a per-face basis. If you want -smooth vertex normals, when adding vertices, call ``add_smooth_group()``. ``add_smooth_group()`` -needs to be called while building the geometry, e.g. before the call to ``add_vertex()`` -(if non-indexed) or ``add_index()`` (if indexed). +smooth vertex normals, when adding vertices, call `add_smooth_group()`. `add_smooth_group()` +needs to be called while building the geometry, e.g. before the call to `add_vertex()` +(if non-indexed) or `add_index()` (if indexed). diff --git a/tutorials/3d/spatial_material.rst b/tutorials/3d/spatial_material.rst index 6b98f1d..567f08b 100644 --- a/tutorials/3d/spatial_material.rst +++ b/tutorials/3d/spatial_material.rst @@ -6,13 +6,13 @@ Spatial Material Introduction ------------ -``SpatialMaterial`` is a default 3D material that aims to provide most of the features +`SpatialMaterial` is a default 3D material that aims to provide most of the features artists look for in a material, without the need for writing shader code. However, it can be converted to shader code if additional functionality is needed. -This tutorial explains most parameters present in ``SpatialMaterial``. +This tutorial explains most parameters present in `SpatialMaterial`. -There are 4 ways to add a ``SpatialMaterial`` to an object. It can be added in +There are 4 ways to add a `SpatialMaterial` to an object. It can be added in the *Material* property of the mesh. It can be added in the *Material* property of the node using the mesh (such as a MeshInstance node), the *Material Override* property of the node using the mesh, and the *Material Overlay*. @@ -163,7 +163,7 @@ option on will help them look correct. Parameters ----------- -``SpatialMaterial`` also has several configurable parameters to tweak +`SpatialMaterial` also has several configurable parameters to tweak many aspects of the rendering: .. image:: img/spatial_material5.png @@ -299,7 +299,7 @@ make it black and unshaded, reverse culling (Cull Front), and add some grow: Use Alpha Scissor ~~~~~~~~~~~~~~~~~ -When transparency other than ``0`` or ``1`` is not needed, it's possible to +When transparency other than `0` or `1` is not needed, it's possible to set a threshold to prevent the object from rendering semi-transparent pixels. .. image:: img/spatial_material12.png @@ -338,10 +338,10 @@ less diffuse/ambient light affects the material and the more light is reflected. This model is called "energy-conserving". The *Specular* parameter is a general amount for the reflectivity (unlike -*Metallic*, this is not energy-conserving, so leave it at ``0.5`` and don't touch +*Metallic*, this is not energy-conserving, so leave it at `0.5` and don't touch it unless you need to). -The minimum internal reflectivity is ``0.04``, so it's impossible to make a +The minimum internal reflectivity is `0.04`, so it's impossible to make a material completely unreflective, just like in real life. .. image:: img/spatial_material13.png @@ -349,8 +349,8 @@ material completely unreflective, just like in real life. Roughness ~~~~~~~~~ -*Roughness* affects the way reflection happens. A value of ``0`` makes it a -perfect mirror while a value of ``1`` completely blurs the reflection (simulating +*Roughness* affects the way reflection happens. A value of `0` makes it a +perfect mirror while a value of `1` completely blurs the reflection (simulating natural microsurfacing). Most common types of materials can be achieved with the right combination of *Metallic* and *Roughness*. @@ -398,8 +398,8 @@ which just use the emission channel, this one actually takes light into account .. image:: img/spatial_material17.png Rim size depends on roughness, and there is a special parameter to specify how -it must be colored. If *Tint* is ``0``, the color of the light is used for the -rim. If *Tint* is ``1``, then the albedo of the material is used. Using +it must be colored. If *Tint* is `0`, the color of the light is used for the +rim. If *Tint* is `1`, then the albedo of the material is used. Using intermediate values generally works best. Clearcoat diff --git a/tutorials/3d/using_multi_mesh_instance.rst b/tutorials/3d/using_multi_mesh_instance.rst index b967e1b..1598fd7 100644 --- a/tutorials/3d/using_multi_mesh_instance.rst +++ b/tutorials/3d/using_multi_mesh_instance.rst @@ -39,7 +39,7 @@ the scene. Your scene tree would look like this: .. 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``. +toolbar, you should see an extra button called `MultiMesh` next to `View`. Click it and select *Populate surface* in the dropdown menu. A new window titled *Populate MultiMesh* will pop up. @@ -95,7 +95,7 @@ The amount of mesh instances placed over the target surface. Select the target surface. In the tree case, this should be the landscape node. The source mesh should be the tree node. Adjust the other parameters -according to your preference. Press ``Populate`` and multiple copies of the +according to your preference. Press `Populate` and multiple copies of the source mesh will be placed over the target mesh. If you are satisfied with the result, you can delete the mesh instance used as the source mesh. diff --git a/tutorials/3d/using_transforms.rst b/tutorials/3d/using_transforms.rst index 51a110e..5e48b96 100644 --- a/tutorials/3d/using_transforms.rst +++ b/tutorials/3d/using_transforms.rst @@ -73,24 +73,24 @@ The camera actually rotated the opposite direction! There are a few reasons this may happen: -* Rotations don't map linearly to orientation, so interpolating them does not always result in the shortest path (i.e., to go from ``270`` to ``0`` degrees is not the same as going from ``270`` to ``360``, even though the angles are equivalent). +* Rotations don't map linearly to orientation, so interpolating them does not always result in the shortest path (i.e., to go from `270` to `0` degrees is not the same as going from `270` to `360`, even though the angles are equivalent). * Gimbal lock is at play (first and last rotated axis align, so a degree of freedom is lost). See `Wikipedia's page on Gimbal Lock `_ for a detailed explanation of this problem. Say no to Euler angles ====================== -The result of all this is that you should **not use** the ``rotation`` property of `Spatial` nodes in Godot for games. It's there to be used mainly in the editor, for coherence with the 2D engine, and for simple rotations (generally just one axis, or even two in limited cases). As much as you may be tempted, don't use it. +The result of all this is that you should **not use** the `rotation` property of `Spatial` nodes in Godot for games. It's there to be used mainly in the editor, for coherence with the 2D engine, and for simple rotations (generally just one axis, or even two in limited cases). As much as you may be tempted, don't use it. Instead, there is a better way to solve your rotation problems. Introducing transforms ---------------------- -Godot uses the `Transform` datatype for orientations. Each `Spatial` node contains a ``transform`` property which is relative to the parent's transform, if the parent is a Spatial-derived type. +Godot uses the `Transform` datatype for orientations. Each `Spatial` node contains a `transform` property which is relative to the parent's transform, if the parent is a Spatial-derived type. -It is also possible to access the world coordinate transform via the ``global_transform`` property. +It is also possible to access the world coordinate transform via the `global_transform` property. -A transform has a `Basis` (transform.basis sub-property), which consists of three `Vector3` vectors. These are accessed via the ``transform.basis`` property and can be accessed directly by ``transform.basis.x``, ``transform.basis.y``, and ``transform.basis.z``. Each vector points in the direction its axis has been rotated, so they effectively describe the node's total rotation. The scale (as long as it's uniform) can also be inferred from the length of the axes. A *basis* can also be interpreted as a 3x3 matrix and used as ``transform.basis[x][y]``. +A transform has a `Basis` (transform.basis sub-property), which consists of three `Vector3` vectors. These are accessed via the `transform.basis` property and can be accessed directly by `transform.basis.x`, `transform.basis.y`, and `transform.basis.z`. Each vector points in the direction its axis has been rotated, so they effectively describe the node's total rotation. The scale (as long as it's uniform) can also be inferred from the length of the axes. A *basis* can also be interpreted as a 3x3 matrix and used as `transform.basis[x][y]`. A default basis (unmodified) is akin to: @@ -106,9 +106,9 @@ gdscript GDScript This is also an analog of a 3x3 identity matrix. -Following the OpenGL convention, ``X`` is the *Right* axis, ``Y`` is the *Up* axis and ``Z`` is the *Forward* axis. +Following the OpenGL convention, `X` is the *Right* axis, `Y` is the *Up* axis and `Z` is the *Forward* axis. -Together with the *basis*, a transform also has an *origin*. This is a *Vector3* specifying how far away from the actual origin ``(0, 0, 0)`` this transform is. Combining the *basis* with the *origin*, a *transform* efficiently represents a unique translation, rotation, and scale in space. +Together with the *basis*, a transform also has an *origin*. This is a *Vector3* specifying how far away from the actual origin `(0, 0, 0)` this transform is. Combining the *basis* with the *origin*, a *transform* efficiently represents a unique translation, rotation, and scale in space. .. image:: img/transforms_camera.png @@ -117,7 +117,7 @@ One way to visualize a transform is to look at an object's 3D gizmo while in "lo .. image:: img/transforms_local_space.png -The gizmo's arrows show the ``X``, ``Y``, and ``Z`` axes (in red, green, and blue respectively) of the basis, while the gizmo's center is at the object's origin. +The gizmo's arrows show the `X`, `Y`, and `Z` axes (in red, green, and blue respectively) of the basis, while the gizmo's center is at the object's origin. .. image:: img/transforms_gizmo.png @@ -166,7 +166,7 @@ gdscript GDScript Precision errors ================ -Doing successive operations on transforms will result in a loss of precision due to floating-point error. This means the scale of each axis may no longer be exactly ``1.0``, and they may not be exactly ``90`` degrees from each other. +Doing successive operations on transforms will result in a loss of precision due to floating-point error. This means the scale of each axis may no longer be exactly `1.0`, and they may not be exactly `90` degrees from each other. If a transform is rotated every frame, it will eventually start deforming over time. This is unavoidable. @@ -178,7 +178,7 @@ gdscript GDScript transform = transform.orthonormalized() ``` -This will make all axes have ``1.0`` length again and be ``90`` degrees from each other. However, any scale applied to the transform will be lost. +This will make all axes have `1.0` length again and be `90` degrees from each other. However, any scale applied to the transform will be lost. It is recommended you not scale nodes that are going to be manipulated; scale their children nodes instead (such as MeshInstance). If you absolutely must scale the node, then re-apply it at the end: @@ -194,7 +194,7 @@ Obtaining information You might be thinking at this point: **"Ok, but how do I get angles from a transform?"**. The answer again is: you don't. You must do your best to stop thinking in angles. -Imagine you need to shoot a bullet in the direction your player is facing. Just use the forward axis (commonly ``Z`` or ``-Z``). +Imagine you need to shoot a bullet in the direction your player is facing. Just use the forward axis (commonly `Z` or `-Z`). gdscript GDScript diff --git a/tutorials/animation/2d_skeletons.rst b/tutorials/animation/2d_skeletons.rst index 2e8bd45..8c85e4c 100644 --- a/tutorials/animation/2d_skeletons.rst +++ b/tutorials/animation/2d_skeletons.rst @@ -51,10 +51,10 @@ Creating the polygons --------------------- Create a new scene for your model (if it's going to be an animated character, -you may want to use a ``KinematicBody2D``). For ease of use, an empty 2D node is +you may want to use a `KinematicBody2D`). For ease of use, an empty 2D node is created as a root for the polygons. -Begin with a ``Polygon2D`` node. There is no need to place it anywhere in the +Begin with a `Polygon2D` node. There is no need to place it anywhere in the scene for now, so simply create it like this: .. image:: img/skel2d1.png @@ -110,12 +110,12 @@ And there you go! It was definitely much easier than in the cutout tutorial. Creating the skeleton --------------------- -Create a ``Skeleton2D`` node as a child of the root node. This will be the base +Create a `Skeleton2D` node as a child of the root node. This will be the base of our skeleton: .. image:: img/skel2d9.png -Create a ``Bone2D`` node as a child of the skeleton. Put it on the hip (usually +Create a `Bone2D` node as a child of the skeleton. Put it on the hip (usually skeletons start here). The bone will be pointing to the right, but you can ignore this for now. @@ -154,7 +154,7 @@ Deforming the polygons ---------------------- Select the previously created polygons and assign the skeleton node to their -``Skeleton`` property. This will ensure that they can eventually be deformed by +`Skeleton` property. This will ensure that they can eventually be deformed by it. .. image:: img/skel2d15.png diff --git a/tutorials/animation/animation_tree.rst b/tutorials/animation/animation_tree.rst index 8b5d5f7..6a93083 100644 --- a/tutorials/animation/animation_tree.rst +++ b/tutorials/animation/animation_tree.rst @@ -10,65 +10,65 @@ With `AnimationPlayer`, Godot has one of the most flexible animation systems tha The ability to animate almost any property in any node or resource, as well as having dedicated transform, bezier, function calling, audio and sub-animation tracks, is pretty much unique. -However, the support for blending those animations via ``AnimationPlayer`` is relatively limited, as only a fixed cross-fade transition time can be set. +However, the support for blending those animations via `AnimationPlayer` is relatively limited, as only a fixed cross-fade transition time can be set. `AnimationTree` is a new node introduced in Godot 3.1 to deal with advanced transitions. -It supersedes the ancient ``AnimationTreePlayer``, while adding a huge amount of features and flexibility. +It supersedes the ancient `AnimationTreePlayer`, while adding a huge amount of features and flexibility. Creating an AnimationTree ------------------------- -Before starting, it must be made clear that an ``AnimationTree`` node does not contain its own animations. -Instead, it uses animations contained in an ``AnimationPlayer`` node. This way, you can edit your animations (or import them from a 3D scene) +Before starting, it must be made clear that an `AnimationTree` node does not contain its own animations. +Instead, it uses animations contained in an `AnimationPlayer` node. This way, you can edit your animations (or import them from a 3D scene) as usual and then use this extra node to control the playback. -The most common way to use ``AnimationTree`` is in a 3D scene. When importing your scenes from a 3D exchange format, they will usually come +The most common way to use `AnimationTree` is in a 3D scene. When importing your scenes from a 3D exchange format, they will usually come with animations built-in (either multiple ones or split from a large one on import). -At the end, the imported Godot scene will contain the animations in a ``AnimationPlayer`` node. +At the end, the imported Godot scene will contain the animations in a `AnimationPlayer` node. -As you rarely use imported scenes directly in Godot (they are either instantiated or inherited from), you can place the ``AnimationTree`` node in your -new scene which contains the imported one. Afterwards, point the ``AnimationTree`` node to the ``AnimationPlayer`` that was created in the imported scene. +As you rarely use imported scenes directly in Godot (they are either instantiated or inherited from), you can place the `AnimationTree` node in your +new scene which contains the imported one. Afterwards, point the `AnimationTree` node to the `AnimationPlayer` that was created in the imported scene. This is how it's done in the `Third Person Shooter demo `_, for reference: .. image:: img/animtree1.png -A new scene was created for the player with a ``KinematicBody`` as root. Inside this scene, the original ``.dae`` (Collada) file was instantiated -and an ``AnimationTree`` node was created. +A new scene was created for the player with a `KinematicBody` as root. Inside this scene, the original `.dae` (Collada) file was instantiated +and an `AnimationTree` node was created. Creating a tree --------------- -There are three main types of nodes that can be used in ``AnimationTree``: +There are three main types of nodes that can be used in `AnimationTree`: -1. Animation nodes, which reference an animation from the linked ``AnimationTree``. +1. Animation nodes, which reference an animation from the linked `AnimationTree`. 2. Animation Root nodes, which are used to blend sub-nodes. -3. Animation Blend nodes, which are used within ``AnimationNodeBlendTree`` as single-graph blending via multiple input ports. +3. Animation Blend nodes, which are used within `AnimationNodeBlendTree` as single-graph blending via multiple input ports. -To set a root node in ``AnimationTree``, a few types are available: +To set a root node in `AnimationTree`, a few types are available: .. image:: img/animtree2.png -* ``AnimationNodeAnimation``: Selects an animation from the list and plays it. This is the simplest root node, and generally not used directly as root. -* ``AnimationNodeBlendTree``: Contains many *blend* type nodes, such as mix, blend2, blend3, one shot, etc. This is one of the most commonly used roots. -* ``AnimationNodeStateMachine``: Contains multiple root nodes as children in a graph. Each node is used as a *state*, and provides multiple functions to alternate between states. -* ``AnimationNodeBlendSpace2D``: Allows placing root nodes in a 2D blend space. Control the blend position in 2D to mix between multiple animations. -* ``AnimationNodeBlendSpace1D``: Simplified version of the above (1D). +* `AnimationNodeAnimation`: Selects an animation from the list and plays it. This is the simplest root node, and generally not used directly as root. +* `AnimationNodeBlendTree`: Contains many *blend* type nodes, such as mix, blend2, blend3, one shot, etc. This is one of the most commonly used roots. +* `AnimationNodeStateMachine`: Contains multiple root nodes as children in a graph. Each node is used as a *state*, and provides multiple functions to alternate between states. +* `AnimationNodeBlendSpace2D`: Allows placing root nodes in a 2D blend space. Control the blend position in 2D to mix between multiple animations. +* `AnimationNodeBlendSpace1D`: Simplified version of the above (1D). Blend tree ---------- -An ``AnimationNodeBlendTree`` can contain both root and regular nodes used for blending. Nodes are added to the graph from a menu: +An `AnimationNodeBlendTree` can contain both root and regular nodes used for blending. Nodes are added to the graph from a menu: .. image:: img/animtree3.png -All blend trees contain an ``Output`` node by default, and something has to be connected to it in order for animations to play. +All blend trees contain an `Output` node by default, and something has to be connected to it in order for animations to play. -The easiest way to test this functionality is to connect an ``Animation`` node to it directly: +The easiest way to test this functionality is to connect an `Animation` node to it directly: .. image:: img/animtree4.png -This will simply play back the animation. Make sure that the ``AnimationTree`` is active for something to actually happen. +This will simply play back the animation. Make sure that the `AnimationTree` is active for something to actually happen. Following is a short description of available nodes: @@ -96,9 +96,9 @@ This node will execute a sub-animation and return once it finishes. Blend times Seek ^^^^ -This node can be used to cause a seek command to happen to any sub-children of the animation graph. Use this node type to play an ``Animation`` from the start or a certain playback position inside the ``AnimationNodeBlendTree``. +This node can be used to cause a seek command to happen to any sub-children of the animation graph. Use this node type to play an `Animation` from the start or a certain playback position inside the `AnimationNodeBlendTree`. -After setting the time and changing the animation playback, the seek node automatically goes into sleep mode on the next process frame by setting its ``seek_position`` value to ``-1.0``. +After setting the time and changing the animation playback, the seek node automatically goes into sleep mode on the next process frame by setting its `seek_position` value to `-1.0`. gdscript GDScript @@ -122,12 +122,12 @@ Allows scaling the speed of the animation (or reverse it) in any children nodes. Transition ^^^^^^^^^^ -Very simple state machine (when you don't want to cope with a ``StateMachine`` node). Animations can be connected to the outputs and transition times can be specified. +Very simple state machine (when you don't want to cope with a `StateMachine` node). Animations can be connected to the outputs and transition times can be specified. BlendSpace2D ^^^^^^^^^^^^ -``BlendSpace2D`` is a node to do advanced blending in two dimensions. Points are added to a two-dimensional space and then a position +`BlendSpace2D` is a node to do advanced blending in two dimensions. Points are added to a two-dimensional space and then a position can be controlled to determine blending: .. image:: img/animtree7.gif @@ -178,7 +178,7 @@ Transitions also have a few properties. Click any transition and it will be disp * *Advance Condition* will turn on auto advance when this condition is set. This is a custom text field that can be filled with a variable name. The variable can be modified from code (more on this later). * *Xfade Time* is the time to cross-fade between this state and the next. -* *Priority* is used together with the ``travel()`` function from code (more on this later). Lower priority transitions are preferred when travelling through the tree. +* *Priority* is used together with the `travel()` function from code (more on this later). Lower priority transitions are preferred when travelling through the tree. * *Disabled* toggles disabling this transition (when disabled, it will not be used during travel or auto advance). @@ -203,7 +203,7 @@ gdscript GDScript This can be fed to functions such as `KinematicBody.move_and_slide` to control the character movement. -There is also a tool node, ``RootMotionView``, that can be placed in a scene and will act as a custom floor for your +There is also a tool node, `RootMotionView`, that can be placed in a scene and will act as a custom floor for your character and animations (this node is disabled by default during the game). .. image:: img/animtree15.gif @@ -215,16 +215,16 @@ Controlling from code After building the tree and previewing it, the only question remaining is "How is all this controlled from code?". Keep in mind that the animation nodes are just resources and, as such, they are shared between all instances using them. -Setting values in the nodes directly will affect all instances of the scene that uses this ``AnimationTree``. +Setting values in the nodes directly will affect all instances of the scene that uses this `AnimationTree`. This is generally undesirable, but does have some cool use cases, e.g. you can copy and paste parts of your animation tree, or reuse nodes with a complex layout (such as a state machine or blend space) in different animation trees. -The actual animation data is contained in the ``AnimationTree`` node and is accessed via properties. -Check the "Parameters" section of the ``AnimationTree`` node to see all the parameters that can be modified in real-time: +The actual animation data is contained in the `AnimationTree` node and is accessed via properties. +Check the "Parameters" section of the `AnimationTree` node to see all the parameters that can be modified in real-time: .. image:: img/animtree16.png -This is handy because it makes it possible to animate them from an ``AnimationPlayer``, or even the ``AnimationTree`` itself, +This is handy because it makes it possible to animate them from an `AnimationPlayer`, or even the `AnimationTree` itself, allowing the realization of very complex animation logic. To modify these values from code, the property path must be obtained. This is done easily by hovering the mouse over any of the parameters: @@ -245,13 +245,13 @@ gdscript GDScript State machine travel -------------------- -One of the nice features in Godot's ``StateMachine`` implementation is the ability to travel. The graph can be instructed to go from the +One of the nice features in Godot's `StateMachine` implementation is the ability to travel. The graph can be instructed to go from the current state to another one, while visiting all the intermediate ones. This is done via the A\* algorithm. In the absence of any viable set of transitions starting at the current state and finishing at the destination state, the graph teleports to the destination state. To use the travel ability, you should first retrieve the `AnimationNodeStateMachinePlayback` -object from the ``AnimationTree`` node (it is exported as a property). +object from the `AnimationTree` node (it is exported as a property). gdscript GDScript @@ -268,6 +268,6 @@ gdscript GDScript state_machine.travel("SomeState") ``` -The state machine must be running before you can travel. Make sure to either call ``start()`` or choose a node to **Autoplay on Load**. +The state machine must be running before you can travel. Make sure to either call `start()` or choose a node to **Autoplay on Load**. .. image:: img/animtree18.png diff --git a/tutorials/animation/cutout_animation.rst b/tutorials/animation/cutout_animation.rst index d3a285d..4aa897c 100644 --- a/tutorials/animation/cutout_animation.rst +++ b/tutorials/animation/cutout_animation.rst @@ -122,7 +122,7 @@ We want the left arm to appear *behind* the hip and the torso. We could move the left arm nodes behind the hip (above 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. +of the torso. We'll fix this problem with `RemoteTransform2D` nodes. .. note:: You can also fix depth ordering problems by adjusting the Z property of any node inheriting from Node2D. @@ -137,15 +137,15 @@ any transformation it inherits from its parents) to the remote node it targets. This allows us to correct the visibility order of our elements, independently of the locations of those parts in the cutout hierarchy. -Create a ``RemoteTransform2D`` node as a child of the torso. Call it ``remote_arm_l``. -Create another RemoteTransform2D node inside the first and call it ``remote_hand_l``. -Use the ``Remote Path`` property of the two new nodes to target the ``arm_l`` and -``hand_l`` sprites respectively: +Create a `RemoteTransform2D` node as a child of the torso. Call it `remote_arm_l`. +Create another RemoteTransform2D node inside the first and call it `remote_hand_l`. +Use the `Remote Path` property of the two new nodes to target the `arm_l` and +`hand_l` sprites respectively: .. image:: img/tuto_cutout9.png -Moving the ``RemoteTransform2D`` nodes now moves the sprites. So we can create -animations by adjusting the ``RemoteTransform2D`` transforms: +Moving the `RemoteTransform2D` nodes now moves the sprites. So we can create +animations by adjusting the `RemoteTransform2D` transforms: .. image:: img/tutovec_torso4.gif @@ -180,7 +180,7 @@ a skeleton, a chain of nodes must be selected from top to bottom: .. image:: img/tuto_cutout11.png -Then, click on the Skeleton menu and select ``Make Bones``. +Then, click on the Skeleton menu and select `Make Bones`. .. image:: img/tuto_cutout12.png @@ -214,7 +214,7 @@ between all of them. You may notice that an extra bone is created when connecting the hip and torso. Godot has connected the hip node to the scene root with a bone, and we don't want that. To fix this, select the root and hip node, open the Skeleton menu, -click ``clear bones``. +click `clear bones`. .. image:: img/tuto_cutout15_2.png diff --git a/tutorials/animation/introduction.rst b/tutorials/animation/introduction.rst index 21b1512..88e9151 100644 --- a/tutorials/animation/introduction.rst +++ b/tutorials/animation/introduction.rst @@ -233,9 +233,9 @@ values. This can be: - **Discrete:** Only update the property on keyframes. - **Trigger:** Only update the property on keyframes or triggers. Triggers are a type of keyframe used by the - ``current_animation`` property of a `AnimationPlayer`, + `current_animation` property of a `AnimationPlayer`, and Animation Playback tracks. -- **Capture:** If the first keyframe's time is greater than ``0.0``, the +- **Capture:** If the first keyframe's time is greater than `0.0`, the current value of the property will be remembered and will be blended with the first animation key. For example, you could use the Capture mode to move a node that's located anywhere @@ -393,9 +393,9 @@ then add tracks for each property that you want to reset. The only keyframe should be at time 0, and give it the desired default value for each track. -If AnimationPlayer's **Reset On Save** property is set to ``true``, +If AnimationPlayer's **Reset On Save** property is set to `true`, the scene will be saved with the effects of the reset animation applied -(as if it had been seeked to time ``0.0``). +(as if it had been seeked to time `0.0`). This only affects the saved file – the property tracks in the editor stay where they were. diff --git a/tutorials/animation/playing_videos.rst b/tutorials/animation/playing_videos.rst index 2cd8ba7..3522b80 100644 --- a/tutorials/animation/playing_videos.rst +++ b/tutorials/animation/playing_videos.rst @@ -23,11 +23,11 @@ Therefore, **using WebM is not recommended**. .. note:: - You may find videos with an ``.ogg`` or ``.ogx`` extensions, which are generic + You may find videos with an `.ogg` or `.ogx` extensions, which are generic extensions for data within an Ogg container. - Renaming these file extensions to ``.ogv`` *may* allow the videos to be - imported in Godot. However, not all files with ``.ogg`` or ``.ogx`` + Renaming these file extensions to `.ogv` *may* allow the videos to be + imported in Godot. However, not all files with `.ogg` or `.ogx` extensions are videos - some of them may only contain audio. Setting up VideoPlayer @@ -35,14 +35,14 @@ Setting up VideoPlayer 1. Create a VideoPlayer node using the Create New Node dialog. 2. Select the VideoPlayer node in the scene tree dock, go to the inspector - and load an ``.ogv`` file in the Stream property. + and load an `.ogv` file in the Stream property. - If you don't have your video in Ogg Theora format yet, jump to `doc_playing_videos_recommended_theora_encoding_settings`. 3. If you want the video to play as soon as the scene is loaded, check **Autoplay** in the inspector. If not, leave **Autoplay** disabled and call - ``play()`` on the VideoPlayer node in a script to start playback when + `play()` on the VideoPlayer node in a script to start playback when desired. Handling resizing and different aspect ratios @@ -187,24 +187,24 @@ below with almost any input video format (AVI, MOV, WebM, …). .. 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 - at the ``configuration:`` line in the command output. + You can check this by running `ffmpeg` without any arguments, then looking + at the `configuration:` line in the command output. Balancing quality and file size ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The **video quality** level (``-q:v``) must be between ``1`` and ``10``. Quality -``6`` is a good compromise between quality and file size. If encoding at a high -resolution (such as 1440p or 4K), you will probably want to decrease ``-q:v`` to -``5`` to keep file sizes reasonable. Since pixel density is higher on a 1440p or +The **video quality** level (`-q:v`) must be between `1` and `10`. Quality +`6` is a good compromise between quality and file size. If encoding at a high +resolution (such as 1440p or 4K), you will probably want to decrease `-q:v` to +`5` to keep file sizes reasonable. Since pixel density is higher on a 1440p or 4K video, lower quality presets at higher resolutions will look as good or better compared to low-resolution videos. -The **audio quality** level (``-q:a``) must be between ``-1`` and ``10``. Quality -``6`` provides a good compromise between quality and file size. In contrast to +The **audio quality** level (`-q:a`) must be between `-1` and `10`. Quality +`6` provides a good compromise between quality and file size. In contrast to video quality, increasing audio quality doesn't increase the output file size nearly as much. Therefore, if you want the cleanest audio possible, you can -increase this to ``9`` to get *perceptually lossless* audio. This is especially +increase this to `9` to get *perceptually lossless* audio. This is especially valuable if your input file already uses lossy audio compression. See `this page `__ for a table listing Ogg Vorbis audio quality presets and their respective diff --git a/tutorials/assets_pipeline/escn_exporter/animation.rst b/tutorials/assets_pipeline/escn_exporter/animation.rst index 65066d7..bd34e02 100644 --- a/tutorials/assets_pipeline/escn_exporter/animation.rst +++ b/tutorials/assets_pipeline/escn_exporter/animation.rst @@ -20,27 +20,27 @@ to use this feature: New created action is always an active action bound to object. There are several ways to place an active action into NLA track, -one is of course doing it in ``NLA Editor`` +one is of course doing it in `NLA Editor` .. image:: img/nla_editor.jpg .. image:: img/nla_pushdown.jpg -Or it can be done stashing the action in ``Dope Sheet`` +Or it can be done stashing the action in `Dope Sheet` .. image:: img/dope_sheet.jpg .. image:: img/stash_action.jpg **2. Check mute status of NLA tracks** -An NLA track can be ``mute`` or ``unmute``, the exporter will export all -the ``mute`` NLA track as a separate action, while blends all the ``unmute`` +An NLA track can be `mute` or `unmute`, the exporter will export all +the `mute` NLA track as a separate action, while blends all the `unmute` NLA tracks into every action (including the action action) being exported. .. image:: img/nla_strip.jpg **3. Export the scene** -Make sure the ``Export Stashed Actions`` option has been turned on. +Make sure the `Export Stashed Actions` option has been turned on. .. image:: img/stash_action_option.jpg diff --git a/tutorials/assets_pipeline/escn_exporter/index.rst b/tutorials/assets_pipeline/escn_exporter/index.rst index b4ce750..a950c70 100644 --- a/tutorials/assets_pipeline/escn_exporter/index.rst +++ b/tutorials/assets_pipeline/escn_exporter/index.rst @@ -41,7 +41,7 @@ Build pipeline integration If you have hundreds of model files, you don't want your artists to waste time manually exporting their blend files. To combat this, the exporter provides a -python function ``io_scene_godot.export(out_file_path)`` that can be called to +python function `io_scene_godot.export(out_file_path)` that can be called to export a file. This allows easy integration with other build systems. An example Makefile and python script that exports all the blends in a directory are present in the Godot-Blender-exporter repository. diff --git a/tutorials/assets_pipeline/escn_exporter/material.rst b/tutorials/assets_pipeline/escn_exporter/material.rst index 581b9e1..4eec7f0 100644 --- a/tutorials/assets_pipeline/escn_exporter/material.rst +++ b/tutorials/assets_pipeline/escn_exporter/material.rst @@ -11,20 +11,20 @@ that you cannot see your model with the material applied inside Blender. To do this, the exporter attempts to find Godot materials with names that match those of the material name in Blender. So if you export an object in Blender -with the material name ``PurpleDots`` then the exporter will search for the -file ``PurpleDots.tres`` and assign it to the object. If this file is not a -``SpatialMaterial`` or ``ShaderMaterial`` or if it cannot be found, then the +with the material name `PurpleDots` then the exporter will search for the +file `PurpleDots.tres` and assign it to the object. If this file is not a +`SpatialMaterial` or `ShaderMaterial` or if it cannot be found, then the exporter will fall back to exporting the material from Blender. -Where the exporter searches for the ``.tres`` file is determined by the "Material +Where the exporter searches for the `.tres` file is determined by the "Material Search Paths" option: .. image:: img/material_search.jpg This can take the value of: - - Project Directory - Attempts to find the ``project.Godot`` and recursively - searches through subdirectories. If ``project.Godot`` cannot be found it + - Project Directory - Attempts to find the `project.Godot` and recursively + searches through subdirectories. If `project.Godot` cannot be found it will throw an error. This is useful for most projects where naming conflicts are unlikely. - Export Directory - Look for materials in subdirectories of the export @@ -40,10 +40,10 @@ The exporter has a primitive support for converting Cycles/EEVEE material node t to Godot Shader Material. Note that some of the Shader Node are not supported yet due to difficulties in implementation, which are: -- all the ``noisy textures`` -- ``generated texture coordinates`` -- ``group node`` -- shader nodes except ``PrincipledBSDF``, ``Diffuse``, ``Glossy``, ``Glass``, ``add shader`` and ``mix shader`` +- all the `noisy textures` +- `generated texture coordinates` +- `group node` +- shader nodes except `PrincipledBSDF`, `Diffuse`, `Glossy`, `Glass`, `add shader` and `mix shader` .. warning:: @@ -59,11 +59,11 @@ Generate external materials --------------------------- The default configuration of material exporting would keep all the materials internal to -the ``escn`` file. There is an option which could enable generating external ``.material`` -file when the ``escn`` file opens in Godot. +the `escn` file. There is an option which could enable generating external `.material` +file when the `escn` file opens in Godot. .. image:: img/external_mat_option.jpg -``.material`` file can be assigned to any material slot to be a external resource. +`.material` file can be assigned to any material slot to be a external resource. .. image:: img/gd_dot_material.jpg diff --git a/tutorials/assets_pipeline/escn_exporter/physics.rst b/tutorials/assets_pipeline/escn_exporter/physics.rst index 637bd2d..8214590 100644 --- a/tutorials/assets_pipeline/escn_exporter/physics.rst +++ b/tutorials/assets_pipeline/escn_exporter/physics.rst @@ -30,8 +30,8 @@ are supported: .. image:: img/collision_shapes.jpg There are the following caveats: - - Not all of the collision shapes are supported. Only ``Mesh``, ``Convex - Hull``, ``Capsule``, ``Sphere`` and ``Box`` are supported in both Blender and + - Not all of the collision shapes are supported. Only `Mesh`, `Convex + Hull`, `Capsule`, `Sphere` and `Box` are supported in both Blender and Godot - In Godot, you can have different collision groups and collision masks. In Blender you only have collision groups. As a result, the exported object's diff --git a/tutorials/assets_pipeline/exporting_3d_scenes.rst b/tutorials/assets_pipeline/exporting_3d_scenes.rst index eb8299c..5d1aa71 100644 --- a/tutorials/assets_pipeline/exporting_3d_scenes.rst +++ b/tutorials/assets_pipeline/exporting_3d_scenes.rst @@ -7,8 +7,8 @@ Overview -------- In Godot it is possible to export 3D scenes as a glTF 2.0 file. You can -export as a glTF binary (``.glb`` file) or glTF embedded with textures -(``gltf`` + ``.bin`` + textures). This allows you to create scenes in Godot, +export as a glTF binary (`.glb` file) or glTF embedded with textures +(`gltf` + `.bin` + textures). This allows you to create scenes in Godot, 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. @@ -28,4 +28,4 @@ There are several limitations with glTF export. * No support for exporting particles since their implementation varies across engines. * ShaderMaterials cannot be exported. * No support for exporting 2D scenes. -* Only supported in editor builds (``tools=yes``). +* Only supported in editor builds (`tools=yes`). diff --git a/tutorials/assets_pipeline/import_process.rst b/tutorials/assets_pipeline/import_process.rst index d7dd2ca..67dd248 100644 --- a/tutorials/assets_pipeline/import_process.rst +++ b/tutorials/assets_pipeline/import_process.rst @@ -15,7 +15,7 @@ In Godot 3.0+, we use a more modern approach to importing: Simply drop your assets (image files, scenes, audio files, fonts, etc) directly in the project folder (copy them manually with your OS file explorer). Godot will automatically import these files internally -and keep the imported resources hidden in a ``res://.import`` folder. +and keep the imported resources hidden in a `res://.import` folder. This means that when trying to access imported assets through code you need to use the `Resource Loader` as it will @@ -68,12 +68,12 @@ asset. Files generated ----------------- -Importing will add an extra ``.import`` file, containing the import +Importing will add an extra `.import` file, containing the import configuration. Make sure to commit these to your version control system! .. image:: img/asset_workflow4.png -Additionally, extra assets will be preset in the hidden ``res://.import`` folder: +Additionally, extra assets will be preset in the hidden `res://.import` folder: .. image:: img/asset_workflow5.png diff --git a/tutorials/assets_pipeline/importing_images.rst b/tutorials/assets_pipeline/importing_images.rst index 1de7607..d973ac6 100644 --- a/tutorials/assets_pipeline/importing_images.rst +++ b/tutorials/assets_pipeline/importing_images.rst @@ -8,26 +8,26 @@ Supported image formats Godot can import the following image formats: -- BMP (``.bmp``) +- BMP (`.bmp`) - No support for 16-bit per pixel images. Only 1-bit, 4-bit, 8-bit, 24-bit, and 32-bit per pixel images are supported. -- DirectDraw Surface (``.dds``) +- DirectDraw Surface (`.dds`) - If mipmaps are present in the texture, they will be loaded directly. This can be used to achieve effects using custom mipmaps. -- OpenEXR (``.exr``) +- OpenEXR (`.exr`) - Supports HDR (highly recommended for panorama skies). -- Radiance HDR (``.hdr``) +- Radiance HDR (`.hdr`) - Supports HDR (highly recommended for panorama skies). -- JPEG (``.jpg``, ``.jpeg``) +- JPEG (`.jpg`, `.jpeg`) - Doesn't support transparency per the format's limitations. -- PNG (``.png``) +- PNG (`.png`) - Precision is limited to 8 bits per channel upon importing (no HDR images). -- Truevision Targa (``.tga``) -- SVG (``.svg``, ``.svgz``) +- Truevision Targa (`.tga`) +- SVG (`.svg`, `.svgz`) - SVGs are rasterized using `NanoSVG `__ when importing them. Support is limited; complex vectors may not render correctly. For complex vectors, rendering them to PNGs using Inkscape is often a better solution. This can be automated thanks to its `command-line interface `__. -- WebP (``.webp``) +- WebP (`.webp`) - WebP files support transparency and can be compressed lossily or losslessly. The precision is limited to 8 bits per channel. diff --git a/tutorials/assets_pipeline/importing_scenes.rst b/tutorials/assets_pipeline/importing_scenes.rst index 5f18cd3..6dfbeab 100644 --- a/tutorials/assets_pipeline/importing_scenes.rst +++ b/tutorials/assets_pipeline/importing_scenes.rst @@ -13,7 +13,7 @@ transferred as close as possible. Godot supports the following 3D *scene file formats*: -* glTF 2.0 **(recommended)**. Godot has full support for both text (``.gltf``) and binary (``.glb``) formats. +* glTF 2.0 **(recommended)**. Godot has full support for both text (`.gltf`) and binary (`.glb`) formats. * DAE (COLLADA), an older format that is fully supported. * OBJ (Wavefront) format + their MTL material files. This is also fully supported, but pretty limited (no support for pivots, skeletons, animations, PBR materials, ...). * ESCN, a Godot-specific format that Blender can export with a plugin. @@ -38,8 +38,8 @@ with the latest version of the software. Exporting glTF 2.0 files from Blender ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -There are three ways to export glTF files from Blender. As a glTF binary (``.glb`` file), glTF embedded (``.gltf`` file), -and with textures (``gltf`` + ``.bin`` + textures). +There are three ways to export glTF files from Blender. As a glTF binary (`.glb` file), glTF embedded (`.gltf` file), +and with textures (`gltf` + `.bin` + textures). glTF binary files are the smallest of the three options. They include the mesh and textures set up in Blender. When brought into Godot the textures are part of the object's material file. @@ -181,7 +181,7 @@ Create a script like this: # Do your stuff here. return scene # remember to return the imported scene -The ``post_import`` function takes the imported scene as argument (the +The `post_import` function takes the imported scene as argument (the parameter is actually the root node of the scene). The scene that will finally be used must be returned. It can be a different one. @@ -217,7 +217,7 @@ is modified and re-imported. .. note:: Godot will not reimport materials that are stored in external files unless - you remove the associated ``.material`` file before reimporting. + you remove the associated `.material` file before reimporting. To force reimporting materials every time the 3D scene is reimported, change the material storage mode in the 3D scene by selecting it in the FileSystem @@ -329,18 +329,18 @@ animations should be kept. The filter script is executed against each imported animation. The syntax consists of two types of statements, the first for choosing which animations to filter, and the second for filtering individual tracks within the matched animation. All name patterns are performed using a case -insensitive expression match, using ``?`` and ``*`` wildcards (using ``String.matchn()`` under the +insensitive expression match, using `?` and `*` wildcards (using `String.matchn()` under the hood). The script must start with an animation filter statement (as denoted by the line beginning with an -``@``). For example, if we would like to apply filters to all imported animations which have a name -ending in ``"_Loop"``:: +`@`). For example, if we would like to apply filters to all imported animations which have a name +ending in `"_Loop"`:: @+*_Loop Similarly, additional patterns can be added to the same line, separated by commas. Here is a -modified example to additionally *include* all animations with names that begin with ``"Arm_Left"``, -but also *exclude* all animations which have names ending in ``"Attack"``:: +modified example to additionally *include* all animations with names that begin with `"Arm_Left"`, +but also *exclude* all animations which have names ending in `"Attack"`:: @+*_Loop, +Arm_Left*, -*Attack @@ -353,8 +353,8 @@ animation, this means that one line may include a track, a later rule can still Similarly, a track excluded by an early rule may then be re-included once again by a filter rule further down in the filter script. -For example: include all tracks in animations with names ending in ``"_Loop"``, but discard any -tracks affecting a ``"Skeleton"`` which end in ``"Control"``, unless they have ``"Arm"`` in their +For example: include all tracks in animations with names ending in `"_Loop"`, but discard any +tracks affecting a `"Skeleton"` which end in `"Control"`, unless they have `"Arm"` in their name:: @+*_Loop @@ -362,10 +362,10 @@ name:: -Skeleton:*Control +*Arm* -In the above example, tracks like ``"Skeleton:Leg_Control"`` would be discarded, while tracks such -as ``"Skeleton:Head"`` or ``"Skeleton:Arm_Left_Control"`` would be retained. +In the above example, tracks like `"Skeleton:Leg_Control"` would be discarded, while tracks such +as `"Skeleton:Head"` or `"Skeleton:Arm_Left_Control"` would be retained. -Any track filter lines that do not begin with a ``+`` or ``-`` are ignored. +Any track filter lines that do not begin with a `+` or `-` are ignored. Storage ~~~~~~~ @@ -383,7 +383,7 @@ Clips ~~~~~ It is possible to specify multiple animations from a single timeline as clips. For this to work, the model -must have only one animation that is named ``default``. To create clips, change the clip amount to something +must have only one animation that is named `default`. To create clips, change the clip amount to something greater than zero. You can then name a clip, specify which frames it starts and stops on, and choose whether the animation loops or not. @@ -394,7 +394,7 @@ Scene inheritance ----------------- In many cases, it may be desired to make modifications to the imported scene. By default, this is not possible because -if the source asset changes (source ``.dae``, ``.gltf``, ``.obj`` file re-exported from 3D modelling app), Godot will re-import the whole scene. +if the source asset changes (source `.dae`, `.gltf`, `.obj` file re-exported from 3D modelling app), Godot will re-import the whole scene. It is possible, however, to make local modifications by using *Scene Inheritance*. Try to open the imported scene and the following dialog will appear: @@ -430,19 +430,19 @@ will detect suffixes in object names and will perform actions automatically. Remove nodes (-noimp) ~~~~~~~~~~~~~~~~~~~~~ -Objects that have the ``-noimp`` suffix will be removed at import-time no matter +Objects that have the `-noimp` suffix will be removed at import-time no matter what their type is. They will not appear in the imported scene. Create collisions (-col, -convcol, -colonly, -convcolonly) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The option ``-col`` will work only for Mesh objects. If it is detected, a child +The option `-col` will work only for Mesh objects. If it is detected, a child static collision node will be added, using the same geometry as the mesh. This will create a triangle mesh collision shape, which is a slow, but accurate option for collision detection. This option is usually what you want for level -geometry (but see also ``-colonly`` below). +geometry (but see also `-colonly` below). -The option ``-convcol`` will create a `convexpolygonshape` instead of +The option `-convcol` will create a `convexpolygonshape` instead of a `concavepolygonshape`. Unlike triangle meshes which can be concave, a convex shape can only accurately represent a shape that doesn't have any concave angles (a pyramid is convex, but a hollow box is concave). Due to this, @@ -455,13 +455,13 @@ However, in both cases, the visual geometry may be too complex or not smooth enough for collisions. This can create physics glitches and slow down the engine unnecessarily. -To solve this, the ``-colonly`` modifier exists. It will remove the mesh upon +To solve this, the `-colonly` modifier exists. It will remove the mesh upon importing and will create a `staticbody` collision instead. This helps the visual mesh and actual collision to be separated. -The option ``-convcolonly`` works in a similar way, but will create a `convexpolygonshape` instead. +The option `-convcolonly` works in a similar way, but will create a `convexpolygonshape` instead. -The option ``-colonly`` can also be used with Blender's empty objects. +The option `-colonly` can also be used with Blender's empty objects. On import, it will create a `staticbody` with a collision node as a child. The collision node will have one of a number of predefined shapes, depending on Blender's empty draw type: @@ -491,32 +491,32 @@ reliability. Create navigation (-navmesh) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -A mesh node with the ``-navmesh`` suffix will be converted to a navigation mesh. +A mesh node with the `-navmesh` suffix will be converted to a navigation mesh. The original Mesh object will be removed at import-time. Create a VehicleBody (-vehicle) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -A mesh node with the ``-vehicle`` suffix will be imported as a child to a +A mesh node with the `-vehicle` suffix will be imported as a child to a `VehicleBody` node. Create a VehicleWheel (-wheel) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -A mesh node with the ``-wheel`` suffix will be imported as a child to a +A mesh node with the `-wheel` suffix will be imported as a child to a `VehicleWheel` node. Rigid Body (-rigid) ~~~~~~~~~~~~~~~~~~~ -A mesh node with the ``-rigid`` suffix will be imported as a `RigidBody`. +A mesh node with the `-rigid` suffix will be imported as a `RigidBody`. Animation loop (-loop, -cycle) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Animation clips in the COLLADA document that start or end with the token ``loop`` or ``cycle`` +Animation clips in the COLLADA document that start or end with the token `loop` or `cycle` will be imported as a Godot Animation with the loop flag set. **Unlike the other suffixes described above, this does not require a hyphen.** -In Blender, this requires using the NLA Editor and naming the Action with the ``loop`` or -``cycle`` prefix or suffix. +In Blender, this requires using the NLA Editor and naming the Action with the `loop` or +`cycle` prefix or suffix. diff --git a/tutorials/assets_pipeline/importing_translations.rst b/tutorials/assets_pipeline/importing_translations.rst index 7c17f8b..5e01728 100644 --- a/tutorials/assets_pipeline/importing_translations.rst +++ b/tutorials/assets_pipeline/importing_translations.rst @@ -30,7 +30,7 @@ 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 - loading translations written in the gettext ``.po`` format. See + loading translations written in the gettext `.po` format. See `doc_localization_using_gettext` for details. Translation format @@ -113,7 +113,7 @@ translations to load when the game runs, specified in project.godot (or the project settings). Godot allows loading and removing translations at runtime as well. -Select the ``.csv`` file and access the **Import** dock to define import +Select the `.csv` file and access the **Import** dock to define import options. You can toggle the compression of the imported translations, and select the delimiter to use when parsing the CSV file. diff --git a/tutorials/audio/audio_buses.rst b/tutorials/audio/audio_buses.rst index 51a3d18..5e453c2 100644 --- a/tutorials/audio/audio_buses.rst +++ b/tutorials/audio/audio_buses.rst @@ -298,5 +298,5 @@ Default bus layout ------------------ The default bus layout is automatically saved to the -``res://default_bus_layout.tres`` file. Custom bus arrangements can be saved +`res://default_bus_layout.tres` file. Custom bus arrangements can be saved and loaded from disk. diff --git a/tutorials/audio/audio_streams.rst b/tutorials/audio/audio_streams.rst index 3b350ee..c419799 100644 --- a/tutorials/audio/audio_streams.rst +++ b/tutorials/audio/audio_streams.rst @@ -99,6 +99,6 @@ Both nodes have this property, which must be enabled manually: .. image:: img/audio_stream_doppler.png Enable it by setting it depending on how objects will be moved: -use **Idle** for objects moved using ``_process``, or **Physics** -for objects moved using ``_physics_process``. The tracking will +use **Idle** for objects moved using `_process`, or **Physics** +for objects moved using `_physics_process`. The tracking will happen automatically. diff --git a/tutorials/audio/recording_with_microphone.rst b/tutorials/audio/recording_with_microphone.rst index c9a0ddc..6ec1f46 100644 --- a/tutorials/audio/recording_with_microphone.rst +++ b/tutorials/audio/recording_with_microphone.rst @@ -18,9 +18,9 @@ The structure of the demo The demo consists of a single scene. This scene includes two major parts: the GUI and the audio. -We will focus on the audio part. In this demo, a bus named ``Record`` with the -effect ``Record`` is created to handle the audio recording. -An ``AudioStreamPlayer`` named ``AudioStreamRecord`` is used for recording. +We will focus on the audio part. In this demo, a bus named `Record` with the +effect `Record` is created to handle the audio recording. +An `AudioStreamPlayer` named `AudioStreamRecord` is used for recording. .. image:: img/record_bus.png @@ -68,12 +68,12 @@ gdscript GDScript At the start of the demo, the recording effect is not active. When the user -presses the ``RecordButton``, the effect is enabled with -``set_recording_active(true)``. +presses the `RecordButton`, the effect is enabled with +`set_recording_active(true)`. -On the next button press, as ``effect.is_recording_active()`` is ``true``, -the recorded stream can be stored into the ``recording`` variable by calling -``effect.get_recording()``. +On the next button press, as `effect.is_recording_active()` is `true`, +the recorded stream can be stored into the `recording` variable by calling +`effect.get_recording()`. gdscript GDScript @@ -91,7 +91,7 @@ gdscript GDScript ``` To playback the recording, you assign the recording as the stream of the -``AudioStreamPlayer`` and call ``play()``. +`AudioStreamPlayer` and call `play()`. gdscript GDScript @@ -103,5 +103,5 @@ gdscript GDScript ``` -To save the recording, you call ``save_to_wav()`` with the path to a file. -In this demo, the path is defined by the user via a ``LineEdit`` input box. +To save the recording, you call `save_to_wav()` with the path to a file. +In this demo, the path is defined by the user via a `LineEdit` input box. diff --git a/tutorials/best_practices/autoloads_versus_internal_nodes.rst b/tutorials/best_practices/autoloads_versus_internal_nodes.rst index 2296e4f..844f75e 100644 --- a/tutorials/best_practices/autoloads_versus_internal_nodes.rst +++ b/tutorials/best_practices/autoloads_versus_internal_nodes.rst @@ -20,36 +20,36 @@ many ways to avoid global state thanks to the node tree and signals. For example, let's say we are building a platformer and want to collect coins that play a sound effect. There's a node for that: the `AudioStreamPlayer -`. But if we call the ``AudioStreamPlayer`` while it is +`. But if we call the `AudioStreamPlayer` while it is already playing a sound, the new sound interrupts the first. A solution is to code a global, auto-loaded sound manager class. It generates a -pool of ``AudioStreamPlayer`` nodes that cycle through as each new request for -sound effects comes in. Say we call that class ``Sound``, you can use it from -anywhere in your project by calling ``Sound.play("coin_pickup.ogg")``. This +pool of `AudioStreamPlayer` nodes that cycle through as each new request for +sound effects comes in. Say we call that class `Sound`, you can use it from +anywhere in your project by calling `Sound.play("coin_pickup.ogg")`. This solves the problem in the short term but causes more problems: 1. **Global state**: one object is now responsible for all objects' data. If the - ``Sound`` class has errors or doesn't have an AudioStreamPlayer available, + `Sound` class has errors or doesn't have an AudioStreamPlayer available, all the nodes calling it can break. -2. **Global access**: now that any object can call ``Sound.play(sound_path)`` +2. **Global access**: now that any object can call `Sound.play(sound_path)` from anywhere, there's no longer an easy way to find the source of a bug. -3. **Global resource allocation**: with a pool of ``AudioStreamPlayer`` nodes +3. **Global resource allocation**: with a pool of `AudioStreamPlayer` nodes stored from the start, you can either have too few and face bugs, or too many and use more memory than you need. .. 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 + data to the `Sound` autoload in our example. As a result, the domain to explore to fix the bug spans the entire project. When you keep code inside a scene, only one or two scripts may be involved in audio. -Contrast this with each scene keeping as many ``AudioStreamPlayer`` nodes as it +Contrast this with each scene keeping as many `AudioStreamPlayer` nodes as it needs within itself and all these problems go away: 1. Each scene manages its own state information. If there is a problem with the @@ -66,7 +66,7 @@ Managing shared functionality or data Another reason to use an Autoload can be that you want to reuse the same method or data across many scenes. -In the case of functions, you can create a new type of ``Node`` that provides +In the case of functions, you can create a new type of `Node` that provides that feature for an individual scene using the `name ` keyword in GDScript. @@ -75,7 +75,7 @@ When it comes to data, you can either: 1. Create a new type of `Resource` to share the data. 2. Store the data in an object to which each node has access, for example using - the ``owner`` property to access the scene's root node. + the `owner` property to access the scene's root node. When you should use an Autoload ------------------------------- @@ -95,7 +95,7 @@ Auto-loaded nodes can simplify your code in some cases: Until Godot 3.1, another use was just for convenience: autoloads have a global 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 +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:: @@ -106,4 +106,4 @@ instead to get auto-completion for a type in your entire project. game's node structure or which scene you run, e.g. by pressing :kbd:`F6` key. As a result, you can get the auto-loaded node, for example an autoload called - ``Sound``, by calling ``get_node("/root/Sound")``. + `Sound`, by calling `get_node("/root/Sound")`. diff --git a/tutorials/best_practices/data_preferences.rst b/tutorials/best_practices/data_preferences.rst index 2a18138..f74e904 100644 --- a/tutorials/best_practices/data_preferences.rst +++ b/tutorials/best_practices/data_preferences.rst @@ -18,9 +18,9 @@ Y or Z? This article covers a variety of topics related to these dilemmas. "As the size of a problem domain increases, the runtime length of the algorithm..." - - Constant-time, ``O(1)``: "...does not increase." - - Logarithmic-time, ``O(log n)``: "...increases at a slow rate." - - Linear-time, ``O(n)``: "...increases at the same rate." + - Constant-time, `O(1)`: "...does not increase." + - Logarithmic-time, `O(log n)`: "...increases at a slow rate." + - Linear-time, `O(n)`: "...increases at the same rate." - Etc. Imagine if one had to process 3 million data points within a single frame. It @@ -45,7 +45,7 @@ class. Variants can store Variant-compatible data structures such as `Array` as well as `Object` s. -Godot implements Array as a ``Vector``. The engine stores the Array +Godot implements Array as a `Vector`. The engine stores the Array contents in a contiguous section of memory, i.e. they are in a row adjacent to each other. @@ -55,7 +55,7 @@ to each other. type, meaning that its records can only contain a particular type (denoted by angled brackets). So, for example, a `PoolStringArray` would be something like - a ``Vector``. + a `Vector`. Contiguous memory stores imply the following operation performance: @@ -102,7 +102,7 @@ Contiguous memory stores imply the following operation performance: though. Done by re-sorting the Array after every edit and writing an ordered-aware search algorithm. -Godot implements Dictionary as an ``OrderedHashMap``. The engine +Godot implements Dictionary as an `OrderedHashMap`. The engine stores a small array (initialized to 2^3 or 8 records) of key-value pairs. When one attempts to access a value, they provide it a key. It then *hashes* the key, i.e. converts it into a number. The "hash" is used to calculate the index @@ -255,7 +255,7 @@ Enumerations: int vs. string Most languages offer an enumeration type option. GDScript is no different, but unlike most other languages, it allows one to use either integers or strings for -the enum values (the latter only when using the ``export`` keyword in GDScript). +the enum values (the latter only when using the `export` keyword in GDScript). The question then arises, "which should one use?" The short answer is, "whichever you are more comfortable with." This @@ -268,7 +268,7 @@ up other languages' conventions though, then one should use integers. The primary issue with using integers comes up when one wants to *print* an enum value. As integers, attempting to print MY_ENUM will print -``5`` or what-have-you, rather than something like ``"MyEnum"``. To +`5` or what-have-you, rather than something like `"MyEnum"`. To print an integer enum, one would have to write a Dictionary that maps the corresponding string value for each enum. diff --git a/tutorials/best_practices/godot_interfaces.rst b/tutorials/best_practices/godot_interfaces.rst index 12231ea..55ee2ff 100644 --- a/tutorials/best_practices/godot_interfaces.rst +++ b/tutorials/best_practices/godot_interfaces.rst @@ -73,7 +73,7 @@ Note the following: 3. Keep in mind that loading a resource fetches the cached resource instance maintained by the engine. To get a new object, one must `duplicate` an existing reference - or instantiate one from scratch with ``new()``. + or instantiate one from scratch with `new()`. Nodes likewise have an alternative access point: the SceneTree. @@ -140,7 +140,7 @@ Godot's scripting API is duck-typed. This means that if a script executes an operation, Godot doesn't validate that it supports the operation by **type**. It instead checks that the object **implements** the individual method. -For example, the `CanvasItem` class has a ``visible`` +For example, the `CanvasItem` class has a `visible` property. All properties exposed to the scripting API are in fact a setter and getter pair bound to a name. If one tried to access `CanvasItem.visible`, then Godot would do the @@ -160,10 +160,10 @@ following checks, in order: - If not found, it does an explicit check to see if the user wants to access the "script" or "meta" properties. -- If not, it checks for a ``_set``/``_get`` implementation (depending on type +- If not, it checks for a `_set`/`_get` implementation (depending on type of access) in the CanvasItem and its inherited types. These methods can execute logic that gives the impression that the Object has a property. This - is also the case with the ``_get_property_list`` method. + is also the case with the `_get_property_list` method. - Note that this happens even for non-legal symbol names such as in the case of `TileSet`'s "1/tile_name" property. This @@ -200,7 +200,7 @@ gdscript GDScript - A method check. In the case of `CanvasItem.visible`, one can - access the methods, ``set_visible`` and ``is_visible`` like any other method. + access the methods, `set_visible` and `is_visible` like any other method. gdscript GDScript diff --git a/tutorials/best_practices/godot_notifications.rst b/tutorials/best_practices/godot_notifications.rst index 4f04df1..e054528 100644 --- a/tutorials/best_practices/godot_notifications.rst +++ b/tutorials/best_practices/godot_notifications.rst @@ -8,22 +8,22 @@ Every Object in Godot implements a allow the Object to respond to a variety of engine-level callbacks that may relate to it. For example, if the engine tells a `CanvasItem` to "draw", it will call -``_notification(NOTIFICATION_DRAW)``. +`_notification(NOTIFICATION_DRAW)`. Some of these notifications, like draw, are useful to override in scripts. So much so that Godot exposes many of them with dedicated functions: -- ``_ready()`` : NOTIFICATION_READY +- `_ready()` : NOTIFICATION_READY -- ``_enter_tree()`` : NOTIFICATION_ENTER_TREE +- `_enter_tree()` : NOTIFICATION_ENTER_TREE -- ``_exit_tree()`` : NOTIFICATION_EXIT_TREE +- `_exit_tree()` : NOTIFICATION_EXIT_TREE -- ``_process(delta)`` : NOTIFICATION_PROCESS +- `_process(delta)` : NOTIFICATION_PROCESS -- ``_physics_process(delta)`` : NOTIFICATION_PHYSICS_PROCESS +- `_physics_process(delta)` : NOTIFICATION_PHYSICS_PROCESS -- ``_draw()`` : NOTIFICATION_DRAW +- `_draw()` : NOTIFICATION_DRAW What users might *not* realize is that notifications exist for types other than Node alone: @@ -50,12 +50,12 @@ methods, but are still quite useful. node. - `Popup::NOTIFICATION_POST_POPUP`: - a callback that triggers after a Popup node completes any ``popup*`` method. - Note the difference from its ``about_to_show`` signal which triggers + a callback that triggers after a Popup node completes any `popup*` method. + Note the difference from its `about_to_show` signal which triggers *before* its appearance. One can access all these custom notifications from the universal -``_notification`` method. +`_notification` method. .. note:: Methods in the documentation labeled as "virtual" are also intended to be @@ -63,7 +63,7 @@ One can access all these custom notifications from the universal A classic example is the `_init` method in Object. While it has no - ``NOTIFICATION_*`` equivalent, the engine still calls the method. Most languages + `NOTIFICATION_*` equivalent, the engine still calls the method. Most languages (except C#) rely on it as a constructor. So, in which situation should one use each of these notifications or @@ -72,7 +72,7 @@ virtual functions? _process vs. _physics_process vs. \*_input ------------------------------------------ -Use ``_process`` when one needs a framerate-dependent deltatime between +Use `_process` when one needs a framerate-dependent deltatime between frames. If code that updates object data needs to update as often as possible, this is the right place. Recurring logic checks and data caching often execute here, but it comes down to the frequency at which one needs @@ -91,15 +91,15 @@ gdscript GDScript yield($Timer, "timeout") ``` -Use ``_physics_process`` when one needs a framerate-independent deltatime +Use `_physics_process` when one needs a framerate-independent deltatime between frames. If code needs consistent updates over time, regardless of how fast or slow time advances, this is the right place. Recurring kinematic and object transform operations should execute here. While it is possible, to achieve the best performance, one should avoid -making input checks during these callbacks. ``_process`` and -``_physics_process`` will trigger at every opportunity (they do not "rest" by -default). In contrast, ``*_input`` callbacks will trigger only on frames in +making input checks during these callbacks. `_process` and +`_physics_process` will trigger at every opportunity (they do not "rest" by +default). In contrast, `*_input` callbacks will trigger only on frames in which the engine has actually detected the input. One can check for input actions within the input callbacks just the same. @@ -128,8 +128,8 @@ _init vs. initialization vs. export If the script initializes its own node subtree, without a scene, that code should execute here. Other property or SceneTree-independent -initializations should also run here. This triggers before ``_ready`` or -``_enter_tree``, but after a script creates and initializes its properties. +initializations should also run here. This triggers before `_ready` or +`_enter_tree`, but after a script creates and initializes its properties. Scripts have three types of property assignments that can occur during instantiation: @@ -173,16 +173,16 @@ _ready vs. _enter_tree vs. NOTIFICATION_PARENTED ------------------------------------------------ When instantiating a scene connected to the first executed scene, Godot will -instantiate nodes down the tree (making ``_init`` calls) and build the tree -going downwards from the root. This causes ``_enter_tree`` calls to cascade -down the tree. Once the tree is complete, leaf nodes call ``_ready``. A node +instantiate nodes down the tree (making `_init` calls) and build the tree +going downwards from the root. This causes `_enter_tree` calls to cascade +down the tree. Once the tree is complete, leaf nodes call `_ready`. A node will call this method once all child nodes have finished calling theirs. This then causes a reverse cascade going up back to the tree's root. When instantiating a script or a standalone scene, nodes are not -added to the SceneTree upon creation, so no ``_enter_tree`` callbacks -trigger. Instead, only the ``_init`` call occurs. When the scene is added -to the SceneTree, the ``_enter_tree`` and ``_ready`` calls occur. +added to the SceneTree upon creation, so no `_enter_tree` callbacks +trigger. Instead, only the `_init` call occurs. When the scene is added +to the SceneTree, the `_enter_tree` and `_ready` calls occur. If one needs to trigger behavior that occurs as nodes parent to another, regardless of whether it occurs as part of the main/active scene or not, one diff --git a/tutorials/best_practices/logic_preferences.rst b/tutorials/best_practices/logic_preferences.rst index e0b17b7..9e3b9f7 100644 --- a/tutorials/best_practices/logic_preferences.rst +++ b/tutorials/best_practices/logic_preferences.rst @@ -17,7 +17,7 @@ resources while in the middle of performance-sensitive code. Its counterpart, the `load` method, loads a resource only when it reaches the load statement. That is, it will load a resource in-place which can cause slowdowns when it occurs in the middle of -sensitive processes. The ``load`` function is also an alias for +sensitive processes. The `load` function is also an alias for `ResourceLoader.load(path)` which is accessible to *all* scripting languages. @@ -85,7 +85,7 @@ consider: in exceptional cases, one may wish not to do this: 1. If the 'imported' class is liable to change, then it should be a property - instead, initialized either using an ``export`` or a ``load`` (and + instead, initialized either using an `export` or a `load` (and perhaps not even initialized until later). 2. If the script requires a great many dependencies, and one does not wish @@ -93,7 +93,7 @@ consider: dependencies at runtime as circumstances change. If one preloads resources into constants, then the only way to unload these resources would be to unload the entire script. If they are instead loaded - properties, then one can set them to ``null`` and remove all references + properties, then one can set them to `null` and remove all references to the resource entirely (which, as a `Reference`-extending type, will cause the resources to delete themselves from memory). diff --git a/tutorials/best_practices/project_organization.rst b/tutorials/best_practices/project_organization.rst index 9ec65c5..5478305 100644 --- a/tutorials/best_practices/project_organization.rst +++ b/tutorials/best_practices/project_organization.rst @@ -55,7 +55,7 @@ For consistency across projects, we recommend following these guidelines: as the convention is to name them after the class name which should be in PascalCase. - Use **PascalCase** for node names, as this matches built-in node casing. -- In general, keep third-party resources in a top-level ``addons/`` folder, even +- In general, keep third-party resources in a top-level `addons/` folder, even if they aren't editor plugins. This makes it easier to track which files are third-party. There are some exceptions to this rule; for instance, if you use third-party game assets for a character, it makes more sense to include them @@ -75,21 +75,21 @@ Ignoring specific folders ~~~~~~~~~~~~~~~~~~~~~~~~~ To prevent Godot from importing files contained in a specific folder, create -an empty file called ``.gdignore`` in the folder (the leading ``.`` is required). +an empty file called `.gdignore` in the folder (the leading `.` is required). This can be useful to speed up the initial project importing. .. note:: To create a file whose name starts with a dot on Windows, you can use a text editor such as Notepad++ or use the following command in a - command prompt: ``type nul > .gdignore`` + command prompt: `type nul > .gdignore` Once the folder is ignored, resources in that folder can't be loaded anymore -using the ``load()`` and ``preload()`` methods. Ignoring a folder will also +using the `load()` and `preload()` methods. Ignoring a folder will also automatically hide it from the FileSystem dock, which can be useful to reduce clutter. -Note that the ``.gdignore`` file's contents are ignored, which is why the file -should be empty. It does not support patterns like ``.gitignore`` files do. +Note that the `.gdignore` file's contents are ignored, which is why the file +should be empty. It does not support patterns like `.gitignore` files do. .. _doc_project_organization_case_sensitivity: @@ -100,7 +100,7 @@ Windows and recent macOS versions use case-insensitive filesystems by default, whereas Linux distributions use a case-sensitive filesystem by default. This can cause issues after exporting a project, since Godot's PCK virtual filesystem is case-sensitive. To avoid this, it's recommended to stick to -``snake_case`` naming for all files in the project (and lowercase characters +`snake_case` naming for all files in the project (and lowercase characters in general). .. note:: diff --git a/tutorials/best_practices/scene_organization.rst b/tutorials/best_practices/scene_organization.rst index 8cf2740..ae2f0eb 100644 --- a/tutorials/best_practices/scene_organization.rst +++ b/tutorials/best_practices/scene_organization.rst @@ -206,7 +206,7 @@ be the "main" function. In this case, it would be a Main node. - Node "Main" (main.gd) -The ``main.gd`` script would then serve as the primary controller of one's +The `main.gd` script would then serve as the primary controller of one's game. Then one has their actual in-game "World" (a 2D or 3D one). This can be a child @@ -262,7 +262,7 @@ own place in the hierarchy as a sibling or some other relation. `RemoteTransform` / `RemoteTransform2D` nodes for this purpose. They will allow a target node to conditionally inherit selected transform - elements from the Remote\* node. To assign the ``target`` + elements from the Remote\* node. To assign the `target` `NodePath`, use one of the following: 1. A reliable third party, likely a parent node, to mediate the assignment. @@ -310,7 +310,7 @@ own place in the hierarchy as a sibling or some other relation. 1. The **declarative** solution: place a `Node` in between them. As nodes with no transform, Nodes will not pass along such information to their children. - 2. The **imperative** solution: Use the ``set_as_toplevel`` setter for the + 2. The **imperative** solution: Use the `set_as_toplevel` setter for the `CanvasItem` or `Spatial` node. This will make the node ignore its inherited transform. diff --git a/tutorials/best_practices/scenes_versus_scripts.rst b/tutorials/best_practices/scenes_versus_scripts.rst index 383ae02..5e552d4 100644 --- a/tutorials/best_practices/scenes_versus_scripts.rst +++ b/tutorials/best_practices/scenes_versus_scripts.rst @@ -60,7 +60,7 @@ is much more streamlined. Rather than having to... 2. (Property method) - 1. Scroll down to the bottom of the Inspector to find the ``script`` property and select it. + 1. Scroll down to the bottom of the Inspector to find the `script` property and select it. 2. Select "Load" from the dropdown. @@ -134,9 +134,9 @@ As the size of objects increases, the scripts' necessary size to create and initialize them grows much larger. Creating node hierarchies demonstrates this. Each Node's logic could be several hundred lines of code in length. -The code example below creates a new ``Node``, changes its name, assigns a +The code example below creates a new `Node`, changes its name, assigns a script to it, sets its future parent as its owner so it gets saved to disk along -with it, and finally adds it as a child of the ``Main`` node: +with it, and finally adds it as a child of the `Main` node: gdscript GDScript diff --git a/tutorials/best_practices/version_control_systems.rst b/tutorials/best_practices/version_control_systems.rst index 9ac5d5f..ca74642 100644 --- a/tutorials/best_practices/version_control_systems.rst +++ b/tutorials/best_practices/version_control_systems.rst @@ -27,18 +27,18 @@ Files to exclude from VCS There are some folders Godot creates you should have your VCS ignore: -- ``.import/``: This folder stores all the files it imports automatically based on +- `.import/`: This folder stores all the files it imports automatically based on your source assets and their import flags. -- ``*.translation``: These files are binary imported translations generated from CSV files. -- ``export_presets.cfg``: This file contains all the export presets for the +- `*.translation`: These files are binary imported translations generated from CSV files. +- `export_presets.cfg`: This file contains all the export presets for the project, including sensitive information such as Android keystore credentials. -- ``.mono/``: This folder stores automatically-generated Mono files. It only exists +- `.mono/`: This folder stores automatically-generated Mono files. It only exists in projects that use the Mono version of Godot. Working with Git on Windows --------------------------- -Most Git for Windows clients are configured with the ``core.autocrlf`` set to ``true``. +Most Git for Windows clients are configured with the `core.autocrlf` set to `true`. This can lead to files unnecessarily being marked as modified by Git due to their line endings being converted automatically. It is better to set this option as:: diff --git a/tutorials/best_practices/what_are_godot_classes.rst b/tutorials/best_practices/what_are_godot_classes.rst index 06d40ce..75bb972 100644 --- a/tutorials/best_practices/what_are_godot_classes.rst +++ b/tutorials/best_practices/what_are_godot_classes.rst @@ -23,7 +23,7 @@ These scripts are not technically classes. Instead, they are resources that tell sequence of initializations to perform on one of the engine's built-in classes. Godot's internal classes have methods that register a class's data with a `ClassDB -`. This database provides runtime access to class information. ``ClassDB`` contains +`. This database provides runtime access to class information. `ClassDB` contains information about classes like: - Properties. @@ -31,18 +31,18 @@ information about classes like: - Constants. - Signals. -This ``ClassDB`` is what objects check against when performing an operation like accessing a +This `ClassDB` is what objects check against when performing an operation like accessing a property or calling a method. It checks the database's records and the object's base types' records to see if the object supports the operation. Attaching a `Script` to your object extends the methods, properties, and signals -available from the ``ClassDB``. +available from the `ClassDB`. .. note:: - Even scripts that don't use the ``extends`` keyword implicitly inherit from the engine's base + Even scripts that don't use the `extends` keyword implicitly inherit from the engine's base `Reference` class. As a result, you can instantiate scripts without the - ``extends`` keyword from code. Since they extend ``Reference`` though, you cannot attach them to + `extends` keyword from code. Since they extend `Reference` though, you cannot attach them to a `Node`. Scenes @@ -50,7 +50,7 @@ Scenes The behavior of scenes has many similarities to classes, so it can make sense to think of a scene as a class. Scenes are reusable, instantiable, and inheritable groups of nodes. Creating a scene is -similar to having a script that creates nodes and adds them as children using ``add_child()``. +similar to having a script that creates nodes and adds them as children using `add_child()`. We often pair a scene with a scripted root node that makes use of the scene's nodes. As such, the scene is often an extension of the script's declarative code. diff --git a/tutorials/editor/command_line_tutorial.rst b/tutorials/editor/command_line_tutorial.rst index 4a768b3..cd1fe68 100644 --- a/tutorials/editor/command_line_tutorial.rst +++ b/tutorials/editor/command_line_tutorial.rst @@ -17,11 +17,11 @@ suitable for this workflow. its relative or absolute path. On macOS, the process is different due to Godot being contained within an - ``.app`` bundle (which is a *folder*, not a file). To run a Godot binary - from a terminal on macOS, you have to ``cd`` to the folder where the Godot - application bundle is located, then run ``Godot.app/Contents/MacOS/Godot`` + `.app` bundle (which is a *folder*, not a file). To run a Godot binary + from a terminal on macOS, you have to `cd` to the folder where the Godot + application bundle is located, then run `Godot.app/Contents/MacOS/Godot` followed by any command line arguments. If you've renamed the application - bundle from ``Godot`` to another name, make sure to edit this command line + bundle from `Godot` to another name, make sure to edit this command line accordingly. Command line reference @@ -32,13 +32,13 @@ Command line reference +----------------------------+----------------------------------------------------------------------+ | Command | Description | +----------------------------+----------------------------------------------------------------------+ -| ``-h``, ``--help``, ``/?`` | Display the list of command line options. | +| `-h`, `--help`, `/?` | Display the list of command line options. | +----------------------------+----------------------------------------------------------------------+ -| ``--version`` | Display the version string. | +| `--version` | Display the version string. | +----------------------------+----------------------------------------------------------------------+ -| ``-v``, ``--verbose`` | Use verbose stdout mode. | +| `-v`, `--verbose` | Use verbose stdout mode. | +----------------------------+----------------------------------------------------------------------+ -| ``--quiet`` | Quiet mode, silences stdout messages. Errors are still displayed. | +| `--quiet` | Quiet mode, silences stdout messages. Errors are still displayed. | +----------------------------+----------------------------------------------------------------------+ **Run options** @@ -46,27 +46,27 @@ Command line reference +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Command | Description | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``-e``, ``--editor`` | Start the editor instead of running the scene (`tools ` must be enabled). | +| `-e`, `--editor` | Start the editor instead of running the scene (`tools ` must be enabled). | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``-p``, ``--project-manager`` | Start the project manager, even if a project is auto-detected (`tools ` must be enabled). | +| `-p`, `--project-manager` | Start the project manager, even if a project is auto-detected (`tools ` must be enabled). | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``-q``, ``--quit`` | Quit after the first iteration. | +| `-q`, `--quit` | Quit after the first iteration. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``-l ``, ``--language `` | Use a specific locale ( being a two-letter code). See `doc_locales` for more details. | +| `-l `, `--language ` | Use a specific locale ( being a two-letter code). See `doc_locales` for more details. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--path `` | Path to a project ( must contain a 'project.godot' file). | +| `--path ` | Path to a project ( must contain a 'project.godot' file). | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``-u``, ``--upwards`` | Scan folders upwards for 'project.godot' file. | +| `-u`, `--upwards` | Scan folders upwards for 'project.godot' file. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--main-pack `` | Path to a pack (.pck) file to load. | +| `--main-pack ` | Path to a pack (.pck) file to load. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--render-thread `` | Render thread mode ('unsafe', 'safe', 'separate'). See `Thread Model` for more details. | +| `--render-thread ` | Render thread mode ('unsafe', 'safe', 'separate'). See `Thread Model` for more details. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--remote-fs
`` | Remote filesystem (``[:]`` address). | +| `--remote-fs
` | Remote filesystem (`[:]` address). | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--audio-driver `` | Audio driver. Use ``--help`` first to display the list of available drivers. | +| `--audio-driver ` | Audio driver. Use `--help` first to display the list of available drivers. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--video-driver `` | Video driver. Use ``--help`` first to display the list of available drivers. | +| `--video-driver ` | Video driver. Use `--help` first to display the list of available drivers. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ **Display options** @@ -74,21 +74,21 @@ Command line reference +-----------------------------+----------------------------------------------------------------------------+ | Command | Description | +-----------------------------+----------------------------------------------------------------------------+ -| ``-f``, ``--fullscreen`` | Request fullscreen mode. | +| `-f`, `--fullscreen` | Request fullscreen mode. | +-----------------------------+----------------------------------------------------------------------------+ -| ``-m``, ``--maximized`` | Request a maximized window. | +| `-m`, `--maximized` | Request a maximized window. | +-----------------------------+----------------------------------------------------------------------------+ -| ``-w``, ``--windowed`` | Request windowed mode. | +| `-w`, `--windowed` | Request windowed mode. | +-----------------------------+----------------------------------------------------------------------------+ -| ``-t``, ``--always-on-top`` | Request an always-on-top window. | +| `-t`, `--always-on-top` | Request an always-on-top window. | +-----------------------------+----------------------------------------------------------------------------+ -| ``--resolution x`` | Request window resolution. | +| `--resolution x` | Request window resolution. | +-----------------------------+----------------------------------------------------------------------------+ -| ``--position ,`` | Request window position. | +| `--position ,` | Request window position. | +-----------------------------+----------------------------------------------------------------------------+ -| ``--low-dpi`` | Force low-DPI mode (macOS and Windows only). | +| `--low-dpi` | Force low-DPI mode (macOS and Windows only). | +-----------------------------+----------------------------------------------------------------------------+ -| ``--no-window`` | Run with invisible window. Useful together with ``--script``. | +| `--no-window` | Run with invisible window. Useful together with `--script`. | +-----------------------------+----------------------------------------------------------------------------+ **Debug options** @@ -96,35 +96,35 @@ Command line reference .. note:: Debug options are only available in the editor and debug export templates - (they require ``debug`` or ``release_debug`` build targets, see + (they require `debug` or `release_debug` build targets, see `doc_introduction_to_the_buildsystem_target` for more details). +------------------------------+---------------------------------------------------------------------------------------------+ | Command | Description | +------------------------------+---------------------------------------------------------------------------------------------+ -| ``-d``, ``--debug`` | Debug (local stdout debugger). | +| `-d`, `--debug` | Debug (local stdout debugger). | +------------------------------+---------------------------------------------------------------------------------------------+ -| ``-b``, ``--breakpoints`` | Breakpoint list as source::line comma-separated pairs, no spaces (use %%20 instead). | +| `-b`, `--breakpoints` | Breakpoint list as source::line comma-separated pairs, no spaces (use %%20 instead). | +------------------------------+---------------------------------------------------------------------------------------------+ -| ``--profiling`` | Enable profiling in the script debugger. | +| `--profiling` | Enable profiling in the script debugger. | +------------------------------+---------------------------------------------------------------------------------------------+ -| ``--remote-debug
`` | Remote debug (``:`` address). | +| `--remote-debug
` | Remote debug (`:` address). | +------------------------------+---------------------------------------------------------------------------------------------+ -| ``--debug-collisions`` | Show collision shapes when running the scene. | +| `--debug-collisions` | Show collision shapes when running the scene. | +------------------------------+---------------------------------------------------------------------------------------------+ -| ``--debug-navigation`` | Show navigation polygons when running the scene. | +| `--debug-navigation` | Show navigation polygons when running the scene. | +------------------------------+---------------------------------------------------------------------------------------------+ -| ``--frame-delay `` | Simulate high CPU load (delay each frame by milliseconds). | +| `--frame-delay ` | Simulate high CPU load (delay each frame by milliseconds). | +------------------------------+---------------------------------------------------------------------------------------------+ -| ``--time-scale `` | Force time scale (higher values are faster, 1.0 is normal speed). | +| `--time-scale ` | Force time scale (higher values are faster, 1.0 is normal speed). | +------------------------------+---------------------------------------------------------------------------------------------+ -| ``--disable-render-loop`` | Disable render loop so rendering only occurs when called explicitly from script. | +| `--disable-render-loop` | Disable render loop so rendering only occurs when called explicitly from script. | +------------------------------+---------------------------------------------------------------------------------------------+ -| ``--disable-crash-handler`` | Disable crash handler when supported by the platform code. | +| `--disable-crash-handler` | Disable crash handler when supported by the platform code. | +------------------------------+---------------------------------------------------------------------------------------------+ -| ``--fixed-fps `` | Force a fixed number of frames per second. This setting disables real-time synchronization. | +| `--fixed-fps ` | Force a fixed number of frames per second. This setting disables real-time synchronization. | +------------------------------+---------------------------------------------------------------------------------------------+ -| ``--print-fps`` | Print the frames per second to the stdout. | +| `--print-fps` | Print the frames per second to the stdout. | +------------------------------+---------------------------------------------------------------------------------------------+ **Standalone tools** @@ -132,25 +132,25 @@ Command line reference +----------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Command | Description | +----------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``-s