Relintai/pandemonium_engine_docs
1
0
Fork 0
mirror of https://github.com/Relintai/pandemonium_engine_docs.git synced 2025-04-29 21:57:59 +02:00
Code Issues Packages Projects Releases Wiki Activity

Make backtics use markdown syntax.

Browse Source
This commit is contained in:
Relintai 2023-01-12 19:43:03 +01:00
parent a688b05603
commit 5372295ab9
256 changed files with 3888 additions and 3888 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

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

2
about/complying_with_licenses.rst
View File

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

20
about/faq.rst
View File

@ -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 <doc_command_line_tutorial>` by entering ``godot``.
`run the Godot editor from a terminal <doc_command_line_tutorial>` 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 <https://raw.githubusercontent.com/godotengine/godot/3.x/misc/dist/linux/org.godotengine.Godot.desktop>`__
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?

8
about/list_of_features.rst
View File

@ -495,7 +495,7 @@ Internationalization
- Store localization strings using `CSV <doc_internationalizing_games>`
or `gettext <doc_localization_using_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 <doc_exporting_for_dedicated_servers>` can be
downloaded for Linux and `compiled for macOS <doc_compiling_for_osx>`.
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 <doc_command_line_tutorial>`.
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:**

16
about/release_policy.rst
View File

@ -12,10 +12,10 @@ Godot versioning
----------------
Godot loosely follows `Semantic Versioning <https://semver.org/>`__ 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
------------------------

6
about/troubleshooting.rst
View File

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

22
community/contributing/bisecting_regressions.rst
View File

@ -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 <https://downloads.tuxfamily.org/godotengine/>`__, 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 <doc_getting_source>`. 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=<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 <https://git-scm.com/docs/git-bisect>`__.

2
community/contributing/bug_triage_guidelines.rst
View File

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

20
community/contributing/building_the_manual.rst
View File

@ -14,14 +14,14 @@ To get started, you need to:
3. To build the docs as HTML files, install the `readthedocs.org theme
<https://github.com/snide/sphinx_rtd_theme>`__.
4. Install the Sphinx extensions defined in the `godot-docs repository
<https://github.com/godotengine/godot-docs/>`__ ``requirements.txt`` file.
<https://github.com/godotengine/godot-docs/>`__ `requirements.txt` file.
We recommend using `pip <https://pip.pypa.io>`__, Python’s package manager to
install all these tools. It comes pre-installed with `Python
<https://www.python.org/>`__. Ensure that you install and use Python 3. Here are
the commands to clone the repository and then install all requirements.
.. note:: You may need to write ``python3 -m pip`` (Unix) or ``py -m pip`` (Windows) instead of ``pip3``.
.. note:: You may need to write `python3 -m pip` (Unix) or `py -m pip` (Windows) instead of `pip3`.
If both approaches fail, `check that you have pip3 installed <https://pip.pypa.io/en/stable/installation/>`__.
.. code:: sh
@ -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
<https://github.com/godotengine/godot-docs/issues/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.

14
community/contributing/class_reference_writing_guidelines.rst
View File

@ -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/<module_name>/doc_classes/`` directory instead.
files in the `modules/<module_name>/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 <https://github.com/HaSa1002/codetranslator>`_ to speed up your

52
community/contributing/code_style_guidelines.rst
View File

@ -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 <http://apt.llvm.org/>`__.
- macOS and Windows: You can download precompiled binaries from the
`LLVM website <http://releases.llvm.org/download.html>`__. 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 <path/to/file(s)>
- ``-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 <https://marketplace.visualstudio.com/items?itemName=xaver.clang-format>`__
- Visual Studio: `ClangFormat <https://marketplace.visualstudio.com/items?itemName=LLVMExtensions.ClangFormat>`__
- vim: `vim-clang-format <https://github.com/rhysd/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 <https://www.jetbrains.com/help/clion/clangformat-as-alternative-formatter.html#clion-support>`__
(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 <png.h>``. The block of third-party headers should also be followed
`#include <png.h>`. 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 <path/to/file(s)>
- ``-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:**

2
community/contributing/content_guidelines.rst
View File

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

30
community/contributing/contributing_to_the_documentation.rst
View File

@ -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
<https://github.com/godotengine/godot-docs>`_. 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 <https://github.com/godotengine/godot/tree/master/doc/classes>`__.
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 <http://docutils.sourceforge.net/rst.html>`__ 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
<https://www.sphinx-doc.org/en/stable/index.html>`__ for more details. To learn
how to use Sphinx directives like ``.. note::`` or ``.. seealso::``, check out
how to use Sphinx directives like `.. note::` or `.. seealso::`, check out
the `Sphinx directives documentation
<https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html>`__.
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

26
community/contributing/cpp_usage_guidelines.rst
View File

@ -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 <https://en.wikipedia.org/wiki/Standard_Template_L
as Godot provides its own data types (among other things).
See `doc_faq_why_not_stl` for more information.
This means that pull requests should **not** use ``std::string``,
``std::vector`` and the like. Instead, use Godot's datatypes as described below:
This means that pull requests should **not** use `std::string`,
`std::vector` and the like. Instead, use Godot's datatypes as described below:
- Use ``String`` instead of ``std::string``.
- Use ``Vector`` instead of ``std::vector``. In some cases, ``LocalVector``
- Use `String` instead of `std::string`.
- Use `Vector` instead of `std::vector`. In some cases, `LocalVector`
can be used as an alternative (ask core developers first).
- Use ``Array`` instead of ``std::array``.
- Use `Array` instead of `std::array`.
.. note::
@ -66,10 +66,10 @@ This means that pull requests should **not** use ``std::string``,
in the codebase, it typically performs worse than other datatypes like Vector
and Array. Therefore, List should be avoided in new code unless necessary.
``auto`` keyword
`auto` keyword
^^^^^^^^^^^^^^^^
Please don't use the ``auto`` keyword for type inference. While it can avoid
Please don't use the `auto` keyword for type inference. While it can avoid
repetition, it can also lead to confusing code:
.. code-block:: cpp
@ -84,7 +84,7 @@ Keep in mind hover documentation often isn't readily available for pull request
reviewers. Most of the time, reviewers will use GitHub's online viewer to review
pull requests.
We chose to forbid ``auto`` instead of allowing it on a case-by-case basis to
We chose to forbid `auto` instead of allowing it on a case-by-case basis to
avoid having to decide on difficult edge cases. Thank you for your understanding.
Lambdas
@ -94,11 +94,11 @@ Lambdas should be used conservatively when they make code effectively faster or
simpler, and do not impede readability. Please ask before using lambdas in a
pull request.
``#pragma once`` directive
`#pragma once` directive
^^^^^^^^^^^^^^^^^^^^^^^^^^
To follow the existing style, please use standard ``#ifdef``-based include
guards instead of ``#pragma once`` in new files.
To follow the existing style, please use standard `#ifdef`-based include
guards instead of `#pragma once` in new files.
.. seealso::

84
community/contributing/docs_writing_guidelines.rst
View File

@ -78,7 +78,7 @@ Active:
Use precise action verbs
~~~~~~~~~~~~~~~~~~~~~~~~
Favor precise yet common verbs over generic ones like ``make``, ``set``,
Favor precise yet common verbs over generic ones like `make`, `set`,
and any expression you can replace with a single word.
**Don't** repeat the method's name. It already states it sets the pivot
@ -90,7 +90,7 @@ value to a new one:
Set the pivot position of the 2D node to [code]pivot[/code] value. [...]
**Do** explain what's the consequence of this "set": use precise verbs
like ``place``, ``position``, ``rotate``, ``fade``, etc.
like `place`, `position`, `rotate`, `fade`, etc.
::
@ -127,8 +127,8 @@ continuous in time. Anything like animation or coroutines.
.. tip::
Verbs can turn into adjectival nouns with -ing. This is not a
conjugation, so you may use them: ``the remaining movement``,
``the missing file``, etc.
conjugation, so you may use them: `the remaining movement`,
`the missing file`, etc.
Remove unnecessary adverbs and adjectives
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -165,7 +165,7 @@ Ban these 8 words
Game creation and programming aren't simple, and nothing's easy to
someone learning to use the API for the first time. Other words in the
list, like ``just`` or ``actual`` won't add any info to the sentence.
list, like `just` or `actual` won't add any info to the sentence.
Don't use corresponding adverbs either: obviously, simply, basically,
easily, actually, clearly.
@ -248,7 +248,7 @@ milk" instead.
The region **of the AtlasTexture that is** used.
**Do** use ``'s``. It lets you put the main subject at the start of the
**Do** use `'s`. It lets you put the main subject at the start of the
sentence, and keep it short:
::
@ -338,11 +338,11 @@ The exception is topics that explain static typing concepts to users.
Use real-world code examples where appropriate
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Real-world examples are more accessible to beginners than abstract ``foos`` and
``bars``. You can also copy them directly from your game projects, ensuring that
Real-world examples are more accessible to beginners than abstract `foos` and
`bars`. You can also copy them directly from your game projects, ensuring that
any code snippet compiles without errors.
Writing ``var speed = 10`` rather than ``var my_var = 10`` allows beginners to
Writing `var speed = 10` rather than `var my_var = 10` allows beginners to
understand code better. It gives them a frame of reference as to where they
could use the code snippets in a live project.
@ -370,8 +370,8 @@ could use the code snippets in a live project.
audio_player.play()
Of course, there are times when using real-world examples is impractical. In
those situations, you should still avoid using names such as ``my_var``,
``foo()`` or ``my_func()`` and consider more meaningful names for your examples.
those situations, you should still avoid using names such as `my_var`,
`foo()` or `my_func()` and consider more meaningful names for your examples.
Give an overview of the node in the brief description
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -407,7 +407,7 @@ Mention what methods return if it's useful
Some methods return important values. Describe them at the end of the
description, ideally on a new line. No need to mention the return values
for any method whose name starts with ``set`` or ``get``.
for any method whose name starts with `set` or `get`.
**Don't** use the passive voice:
@ -425,16 +425,16 @@ for any method whose name starts with ``set`` or ``get``.
Notice the exception to the "direct voice" rule: with the move method,
an external collider can influence the method and the body that calls
``move``. In this case, you can use the passive voice.
`move`. In this case, you can use the passive voice.
Use "if true" to describe booleans
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For boolean member variables, always use ``if true`` and/or
``if false``, to stay explicit. ``Controls whether or not`` may be
For boolean member variables, always use `if true` and/or
`if false`, to stay explicit. `Controls whether or not` may be
ambiguous and won't work for every member variable.
Also, surround boolean values, variable names and methods with ``[code][/code]``.
Also, surround boolean values, variable names and methods with `[code][/code]`.
**Do** start with "if true":
@ -444,13 +444,13 @@ Also, surround boolean values, variable names and methods with ``[code][/code]``
If [code]true[/code], the timer will automatically start when entering the scene tree.
Use ``[code]`` around arguments
Use `[code]` around arguments
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In the class reference, always surround arguments with ``[code][/code]``. In the
documentation and in Godot, it will display like ``this``. When you edit XML
In the class reference, always surround arguments with `[code][/code]`. In the
documentation and in Godot, it will display like `this`. When you edit XML
files in the Godot repository, replace existing arguments written like 'this' or
\`this\` with ``[code]this[/code]``.
\`this\` with `[code]this[/code]`.
Common vocabulary to use in Godot's documentation
@ -466,45 +466,45 @@ you're talking about.
Overview of the interface and common vocabulary
In the top left corner of the editor lie the ``main menus``. In the
center, the buttons change the ``workspace``. And together the buttons
in the top right are the ``playtest buttons``. The area in the center,
that displays the 2D or the 3D space, is the ``viewport``. At its top,
you find a list of ``tools`` inside the ``toolbar``.
In the top left corner of the editor lie the `main menus`. In the
center, the buttons change the `workspace`. And together the buttons
in the top right are the `playtest buttons`. The area in the center,
that displays the 2D or the 3D space, is the `viewport`. At its top,
you find a list of `tools` inside the `toolbar`.
The tabs or dockable panels on either side of the viewport are
``docks``. You have the ``FileSystem dock``, the ``Scene dock`` that
contains your scene tree, the ``Import dock``, the ``Node dock``, and
the ``Inspector`` or ``Inspector dock``. With the default layout you may
call the tabbed docks ``tabs``: the ``Scene tab``, the ``Node tab``...
`docks`. You have the `FileSystem dock`, the `Scene dock` that
contains your scene tree, the `Import dock`, the `Node dock`, and
the `Inspector` or `Inspector dock`. With the default layout you may
call the tabbed docks `tabs`: the `Scene tab`, the `Node tab`...
The Animation, Debugger, etc. at the bottom of the viewport are
``panels``. Together they make up the ``bottom panels``.
`panels`. Together they make up the `bottom panels`.
Foldable areas of the Inspector are ``sections``. The node's parent
class names, which you can't fold, are ``Classes`` e.g. the
``KinematicBody2D class``. And individual lines with key-value pairs are
``properties``. E.g. ``position`` or ``modulate color`` are both
``properties``.
Foldable areas of the Inspector are `sections`. The node's parent
class names, which you can't fold, are `Classes` e.g. the
`KinematicBody2D class`. And individual lines with key-value pairs are
`properties`. E.g. `position` or `modulate color` are both
`properties`.
Keyboard shortcut guidelines
----------------------------
Keyboard and mouse shortcuts should make use of the ``:kbd:`` tag, which allows
Keyboard and mouse shortcuts should make use of the `:kbd:` tag, which allows
shortcuts to stand out from the rest of the text and inline code. Use the
compact form for modifier keys (:kbd:`Ctrl`/:kbd:`Cmd`) instead of their spelled
out form (:kbd:`Control`/:kbd:`Command`). For combinations, use the ``+`` symbol
out form (:kbd:`Control`/:kbd:`Command`). For combinations, use the `+` symbol
with a space on either side of the symbol.
Make sure to mention shortcuts that differ on macOS compared to other platforms.
On macOS, ``Cmd`` often replaces ``Ctrl`` in keyboard shortcuts.
On macOS, `Cmd` often replaces `Ctrl` in keyboard shortcuts.
Try to integrate the shortcut into sentences the best you can. Here are some
examples with the ``:kbd:`` tag left as-is for better visibility:
examples with the `:kbd:` tag left as-is for better visibility:
- Press ``:kbd:`Ctrl + Alt + T``` to toggle the panel (``:kbd:`Cmd + Alt + T``` on macOS).
- Press ``:kbd:`Space``` and hold the left mouse button to pan in the 2D editor.
- Press ``:kbd:`Shift + Up Arrow``` to move the node upwards by 8 pixels.
- Press `:kbd:`Ctrl + Alt + T``` to toggle the panel (`:kbd:`Cmd + Alt + T``` on macOS).
- Press `:kbd:`Space``` and hold the left mouse button to pan in the 2D editor.
- Press `:kbd:`Shift + Up Arrow``` to move the node upwards by 8 pixels.
Image contribution guidelines
-----------------------------

4
community/contributing/documentation_guidelines.rst
View File

@ -33,7 +33,7 @@ documentation.
.. warning:: If you want to edit the **API reference**, please note that it
should *not* be done in the godot-docs repository. Instead, you
should edit the ``doc/classes/*`` XML files of Godot's
should edit the `doc/classes/*` XML files of Godot's
main repository. These files are then later used to generate the
in-editor documentation as well as the API reference of the
online docs. Read more here: `doc_updating_the_class_reference`.
@ -98,7 +98,7 @@ Always begin pages with their title and a Sphinx reference name:
Insert your title here
======================
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).

84
community/contributing/editor_and_docs_localization.rst
View File

@ -19,7 +19,7 @@ These resources include:
3. The `class reference <https://hosted.weblate.org/projects/godot-engine/godot-class-reference/>`__,
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 <https://weblate.org>`__ 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 <toc-devel-compiling>`.
Rename the editor translation PO file to ``<lang>.po`` (e.g. ``eo.po`` for
Esperanto) and place it in the ``editor/translations/`` folder
Rename the editor translation PO file to `<lang>.po` (e.g. `eo.po` for
Esperanto) and place it in the `editor/translations/` folder
(`GitHub <https://github.com/godotengine/godot/tree/master/editor/translations>`__).
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 <https://github.com/godotengine/godot/tree/master/doc/translations>`__).
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 <https://github.com/godotengine/godot-docs-l10n/tree/master/images>`_),
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 <doc_pr_workflow>`.

156
community/contributing/pr_workflow.rst
View File

@ -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 <doc_pr_workflow_rebase>` 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 <commit ID>`` or
``git reset --hard <remote>/<branch>`` (e.g. ``git reset --hard upstream/master``).
you can do so with `git reset --hard <commit ID>` or
`git reset --hard <remote>/<branch>` (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 -- <files>`` will undo the unstaged changes to the given
- `git checkout -- <files>` will undo the unstaged changes to the given
files.
- ``git add <files>`` will *stage* the changes on the listed files.
- ``git diff --staged`` will show the current staged changes, i.e. the
- `git add <files>` 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 <files>`` will *unstage* changes to the listed files.
- ``git status`` will show you what are the currently staged and unstaged
- `git reset HEAD <files>` 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 <https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration#_core_editor>`_
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:

4
community/contributing/testing_pull_requests.rst
View File

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

12
community/contributing/updating_the_class_reference.rst
View File

@ -41,10 +41,10 @@ repository: `doc/classes/
<https://github.com/godotengine/godot/tree/master/doc/classes>`_.
.. note:: For some modules in the engine's source code, you'll find the XML
files in the ``modules/<module_name>/doc_classes/`` directory instead.
files in the `modules/<module_name>/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
<toc-class-ref>`, hosted in the `godot-docs
<https://github.com/godotengine/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`.

2
community/contributing/ways_to_contribute.rst
View File

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

44
development/compiling/compiling_for_android.rst
View File

@ -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=<android_sdk_path> --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\<version>\``
- Linux: ``$HOME/.local/share/godot/templates/<version>/``
- macOS: ``$HOME/Library/Application Support/Godot/templates/<version>/``
- Windows: `%APPDATA%\Godot\templates\<version>\`
- Linux: `$HOME/.local/share/godot/templates/<version>/`
- macOS: `$HOME/Library/Application Support/Godot/templates/<version>/`
``<version>`` 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
`<version>` 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 <doc_android_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/<android_arch>/``
where ``<android_arch>`` is the device's architecture.
- `libgodot_android.so` is not in `libs/<android_arch>/`
where `<android_arch>` 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.

8
development/compiling/compiling_for_ios.rst
View File

@ -15,7 +15,7 @@ Requirements
- SCons 3.0+ (you can install it via `Homebrew <https://brew.sh/>`_ or
`MacPorts <https://www.macports.org/>`_, 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.
::

38
development/compiling/compiling_for_osx.rst
View File

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

56
development/compiling/compiling_for_uwp.rst
View File

@ -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 <https://github.com/Microsoft/angle>`__. 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

40
development/compiling/compiling_for_web.rst
View File

@ -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 <doc_javascript_eval>` 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 <doc_javascript_export_options>` 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 <doc_javascript_export_options>` for the web

56
development/compiling/compiling_for_windows.rst
View File

@ -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 <http://mingw-w64.org/>`__ 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+ <https://www.python.org/downloads/windows/>`_.
**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 <https://www.scons.org/>`_ 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 ``<version>`` with the version identifier
(such as ``3.1.1.stable`` or ``3.2.dev``)::
following location, replacing `<version>` with the version identifier
(such as `3.1.1.stable` or `3.2.dev`)::
%USERPROFILE%\AppData\Roaming\Godot\templates\<version>\
@ -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.

40
development/compiling/compiling_for_x11.rst
View File

@ -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 <https://github.com/pyston/pyston/releases/latest>`__.
- 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 <build arguments>``, run ``pyston-scons <build arguments>``
- Instead of running `scons <build arguments>`, run `pyston-scons <build arguments>`
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.

116
development/compiling/compiling_with_mono.rst
View File

@ -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=<platform> 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::
<godot_binary> --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.
``<godot_binary>`` refers to the tools binary you compiled above with the Mono
`<godot_binary>` 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.<platform>.tools.<bits>.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.<platform>.tools.<bits>.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=<platform> tools=yes module_mono_enabled=yes mono_glue=yes
@ -105,13 +105,13 @@ And Mono-enabled export templates::
scons p=<platform> 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.<platform>.<bits>.<target>``, e.g. ``data.mono.x11.32.release_debug`` or
``data.mono.windows.64.release``.
`data.mono.<platform>.<bits>.<target>`, 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_<APPNAME>``, where
``<APPNAME>`` is the application name as specified in the project setting
``application/config/name``.
the game executable but the name will be changed to `data_<APPNAME>`, where
`<APPNAME>` 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.<platform>.<bits>.<target>/Mono/lib`` | ``/osx_template.app/Contents/Frameworks/GodotSharp/Mono/lib`` |
| `bin/data.mono.<platform>.<bits>.<target>/Mono/lib` | `/osx_template.app/Contents/Frameworks/GodotSharp/Mono/lib` |
+-------------------------------------------------------+---------------------------------------------------------------+
| ``bin/data.mono.<platform>.<bits>.<target>/Mono/etc`` | ``/osx_template.app/Contents/Resources/GodotSharp/Mono/etc`` |
| `bin/data.mono.<platform>.<bits>.<target>/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.<platform>.<bits>.<target>/Api`` | ``<bundle_name>.app/Contents/Frameworks/GodotSharp/Api`` |
| `bin/data.mono.<platform>.<bits>.<target>/Api` | `<bundle_name>.app/Contents/Frameworks/GodotSharp/Api` |
+-------------------------------------------------------+---------------------------------------------------------------+
| ``bin/data.mono.<platform>.<bits>.<target>/Mono/lib`` | ``<bundle_name>.app/Contents/Frameworks/GodotSharp/Mono/lib`` |
| `bin/data.mono.<platform>.<bits>.<target>/Mono/lib` | `<bundle_name>.app/Contents/Frameworks/GodotSharp/Mono/lib` |
+-------------------------------------------------------+---------------------------------------------------------------+
| ``bin/data.mono.<platform>.<bits>.<target>/Mono/etc`` | ``<bundle_name>.app/Contents/Resources/GodotSharp/Mono/etc`` |
| `bin/data.mono.<platform>.<bits>.<target>/Mono/etc` | `<bundle_name>.app/Contents/Resources/GodotSharp/Mono/etc` |
+-------------------------------------------------------+---------------------------------------------------------------+
| ``bin/data.mono.<platform>.<bits>.<target>/Tools`` | ``<bundle_name>.app/Contents/Frameworks/GodotSharp/Tools`` |
| `bin/data.mono.<platform>.<bits>.<target>/Tools` | `<bundle_name>.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<doc_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<doc_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 ``<templates>/iphone-mono-libs/lib<name>.iphone.fat.a``.
The `iphone-mono-libs` folder must be distributed with the export templates.
The Godot editor will look for the libraries in `<templates>/iphone-mono-libs/lib<name>.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<doc_compiling_for_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 ``<templates>/bcl/<target_platform>``,
where ``<target_platform>`` is the same name passed to the SCons ``platform`` option,
e.g.: ``<templates>/bcl/windows``, ``<templates>/bcl/javascript``.
Godot looks for the BCL folder at `<templates>/bcl/<target_platform>`,
where `<target_platform>` is the same name passed to the SCons `platform` option,
e.g.: `<templates>/bcl/windows`, `<templates>/bcl/javascript`.
Alternatively, Godot will look for them in the following locations:
+-------------------+---------------------------------+
| Android | ``<templates>/bcl/monodroid`` |
| Android | `<templates>/bcl/monodroid` |
+-------------------+---------------------------------+
| iOS | ``<templates>/bcl/monotouch`` |
| iOS | `<templates>/bcl/monotouch` |
+-------------------+---------------------------------+
| WebAssembly | ``<templates>/bcl/wasm`` |
| WebAssembly | `<templates>/bcl/wasm` |
+-------------------+---------------------------------+
| Linux and macOS | ``<templates>/bcl/net_4_x`` |
| Linux and macOS | `<templates>/bcl/net_4_x` |
+-------------------+---------------------------------+
| Windows | ``<templates>/bcl/net_4_x_win`` |
| Windows | `<templates>/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 (``<data_folder>/Mono/lib/mono/4.5``)
then the editor will use the BCL it's running on (`<data_folder>/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 ``<data_folder>/Tools/aot-compilers/``.
The location of this folder is `<data_folder>/Tools/aot-compilers/`.
In order to build the cross-compilers we recommend using these
`build scripts <https://github.com/godotengine/godot-mono-builds>`_.
After building them, copy the executable to the Godot AOT compilers directory. The
executable name is ``<triple>-mono-sgen``, e.g.: ``aarch64-apple-darwin-mono-sgen``.
executable name is `<triple>-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

4
development/compiling/compiling_with_script_encryption_key.rst
View File

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

18
development/compiling/cross-compiling_for_ios_on_linux.rst
View File

@ -29,8 +29,8 @@ Requirements
- `XCode with the iOS SDK <https://developer.apple.com/xcode/download>`__
(a dmg image)
- `Clang >= 3.5 <http://clang.llvm.org>`__ 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 <https://github.com/libfuse/libfuse>`__ for mounting and umounting
the dmg image.
- `darling-dmg <https://github.com/darlinghq/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.

16
development/compiling/getting_source.rst
View File

@ -13,20 +13,20 @@ and compiling Godot, you need to actually download the Godot source code.
The source code is available on `GitHub <https://github.com/godotengine/godot>`__
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 <doc_pr_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 <https://git-scm.com/book>`__ 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 <https://github.com/godotengine/
and click on the link for the release you want.
You can then download and extract the source from the download link on the page.
With ``git``, you can also clone a stable release by specifying its branch or tag
after the ``--branch`` (or just ``-b``) argument::
With `git`, you can also clone a stable release by specifying its branch or tag
after the `--branch` (or just `-b`) argument::
# Clone the continuously maintained stable branch (`3.x` as of writing).
git clone https://github.com/godotengine/godot.git -b 3.x
@ -48,7 +48,7 @@ after the ``--branch`` (or just ``-b``) argument::
# Clone the `3.2.3-stable` tag. This is a fixed revision that will never change.
git clone https://github.com/godotengine/godot.git -b 3.2.3-stable
There are also generally branches besides ``master`` for each major version.
There are also generally branches besides `master` for each major version.
After downloading the Godot source code,
you can `continue to compiling Godot <doc_introduction_to_the_buildsystem>`.

54
development/compiling/introduction_to_the_buildsystem.rst
View File

@ -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=<string>
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 <cores>`` parameter to specify how many
SCons to build faster, use the `-j <cores>` 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.<platform>.[opt].[tools/debug].<architecture>[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=<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=<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 <options>``, where ``<options>`` is the
can remove them by using `scons --clean <options>`, where `<options>` 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 <https://godot-build-options-generator.github.io/>`__
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 <https://github.com/godotengine/godot/blob/master/version.py>`__.
If you are developing for multiple platforms, macOS is definitely the most

14
development/compiling/optimizing_for_size.rst
View File

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

6
development/cpp/binding_to_external_libraries.rst
View File

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

40
development/cpp/common_engine_methods_and_macros.rst
View File

@ -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 <https://github.com/godotengine/godot/blob/3.x/core/error_list.h>`__.

2
development/cpp/configuring_an_ide/android_studio.rst
View File

@ -20,7 +20,7 @@ Importing the project
Android Studio's welcome window.
- Navigate to ``<Godot root directory>/platform/android/java`` and select the ``settings.gradle`` file.
- Navigate to `<Godot root directory>/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 <toc-devel-compiling>`.

18
development/cpp/configuring_an_ide/clion.rst
View File

@ -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 <doc_configuring_an_ide_android_studio>`
there is a `CMakeLists.txt` configuration for `Android Studio <doc_configuring_an_ide_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 ``<Godot root directory>/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 `<Godot root directory>/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 <https://docs.godotengine.org/en/stable/development/compiling/index.html>`__ and run the binary without CLion. You will then be able to debug Godot by using the `Attach to process <https://www.jetbrains.com/help/clion/attaching-to-local-process.html>`__ 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.

12
development/cpp/configuring_an_ide/code_blocks.rst
View File

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

2
development/cpp/configuring_an_ide/index.rst
View File

@ -4,7 +4,7 @@ Configuring an IDE
We assume that you have already `cloned <https://github.com/godotengine/godot>`_
and `compiled <toc-devel-compiling>` 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:

4
development/cpp/configuring_an_ide/kdevelop.rst
View File

@ -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 ``<Godot root directory>/bin`` folder. The name depends on your build configuration,
e.g. ``godot.x11.tools.64`` for 64-bit X11 platform with ``tools`` enabled.
the `<Godot root directory>/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

20
development/cpp/configuring_an_ide/qt_creator.rst
View File

@ -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 ``<Godot root directory>/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 `<Godot root directory>/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

10
development/cpp/configuring_an_ide/visual_studio.rst
View File

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

18
development/cpp/configuring_an_ide/visual_studio_code.rst
View File

@ -13,7 +13,7 @@ Importing the project
the `official documentation <https://code.visualstudio.com/docs/languages/cpp>`_.
Alternatively, `clangd <https://open-vsx.org/extension/llvm-vs-code-extensions/vscode-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 <https://godotengine.org/community>`__.

12
development/cpp/configuring_an_ide/xcode.rst
View File

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

8
development/cpp/core_types.rst
View File

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

8
development/cpp/custom_audiostreams.rst
View File

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

14
development/cpp/custom_godot_servers.rst
View File

@ -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<MyRID_Data>`` 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<MyRID_Data>` 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:
~~~~~~~~~~~

90
development/cpp/custom_modules_in_cpp.rst
View File

@ -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 <toc-devel-compiling>`.
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 <path>``,
which will dump the engine API reference to the given ``<path>`` in XML format.
We can do this via running Godot's doctool i.e. `godot --doctool <path>`,
which will dump the engine API reference to the given `<path>` 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/<godot_binary> --doctool .
Now if you go to the ``godot/modules/summator/doc_classes`` folder, you will see
that it contains a ``Summator.xml`` file, or any other classes, that you referenced
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 ``<path>``,
Note that if you don't have write access rights to your supplied `<path>`,
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

16
development/cpp/custom_resource_format_loaders.rst
View File

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

2
development/cpp/introduction_to_godot_development.rst
View File

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

4
development/cpp/macos_debug.rst
View File

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

32
development/cpp/object_class.rst
View File

@ -60,13 +60,13 @@ Registering as virtual is the same but it can't be instanced.
ClassDB::register_virtual_class<MyCustomClass>()
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<MyReference> 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:
~~~~~~~~~~~

20
development/cpp/using_cpp_profilers.rst
View File

@ -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 <path to project directory>`` (which runs a project directly).
The `--quit` option works with `--editor`, `--project-manager` or
`--path <path to project directory>` (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.

18
development/editor/creating_icons.rst
View File

@ -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 <https://inkscape.org/>`_ 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 <https://github.com/RazrFalcon/svgcleaner>`__
by downloading a binary from its
`Releases tab <https://github.com/RazrFalcon/svgcleaner/releases/latest>`__
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

8
development/editor/editor_style_guide.rst
View File

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

18
development/editor/introduction_to_editor_development.rst
View File

@ -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 <https://github.com/godotengine/godot/issues/29730>`__.

160
development/file_formats/tscn.rst
View File

@ -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 <https://github.com/godotengine/godot/blob/master/scene/resources/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
``[<resource_type> key=value key=value key=value ...]``
`[<resource_type> 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

14
getting_started/first_2d_game/01.project_setup.rst
View File

@ -14,8 +14,8 @@ GDScript
```
Download :download:`dodge_assets.zip <files/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

30
getting_started/first_2d_game/02.player_scene.rst
View File

@ -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
<class_AnimatedSprite>` node as a child. The ``AnimatedSprite`` will handle the
Click on the `Player` node and add an `AnimatedSprite
<class_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
<class_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

82
getting_started/first_2d_game/03.coding_the_player.rst
View File

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

46
getting_started/first_2d_game/04.creating_the_enemy.rst
View File

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

92
getting_started/first_2d_game/05.the_main_game_scene.rst
View File

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

74
getting_started/first_2d_game/06.heads_up_display.rst
View File

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

24
getting_started/first_2d_game/07.finishing-up.rst
View File

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

18
getting_started/first_3d_game/01.game_setup.rst
View File

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

20
getting_started/first_3d_game/02.player_input.rst
View File

@ -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 <https://www.blender.org/>`__ 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|

54
getting_started/first_3d_game/03.player_movement_code.rst
View File

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

42
getting_started/first_3d_game/04.mob_scene.rst
View File

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

30
getting_started/first_3d_game/05.spawning_mobs.rst
View File

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

54
getting_started/first_3d_game/06.jump_and_squash.rst
View File

@ -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
<doc_groups>` 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_KinematicBody>` class and are related to
``move_and_slide()``.
`move_and_slide()`.
``get_slide_collision()`` returns a
`get_slide_collision()` returns a
`KinematicCollision<class_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<class_Node>`.
The method `is_in_group()` is available on every `Node<class_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.

20
getting_started/first_3d_game/07.killing_player.rst
View File

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

58
getting_started/first_3d_game/08.score_and_replay.rst
View File

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

30
getting_started/first_3d_game/09.adding_animations.rst
View File

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

6
getting_started/introduction/godot_design_philosophy.rst
View File

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

4
getting_started/introduction/key_concepts_overview.rst
View File

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

22
getting_started/step_by_step/instancing.rst
View File

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

2
getting_started/step_by_step/nodes_and_scenes.rst
View File

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

62
getting_started/step_by_step/scripting_first_script.rst
View File

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

54
getting_started/step_by_step/scripting_player_input.rst
View File

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

42
getting_started/step_by_step/signals.rst
View File

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

4
index.rst
View File

@ -40,7 +40,7 @@ in the top left corner.
You can also `download an HTML copy <https://nightly.link/godotengine/godot-docs/workflows/build_offline_docs/master/godot-docs-html-stable.zip>`__
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
<https://hosted.weblate.org/engage/godot-engine/>`_ into your
language, or talk to us on the
``#documentation`` channel on the `Godot Contributors Chat
`#documentation` channel on the `Godot Contributors Chat
<https://chat.godotengine.org/>`_!
.. centered:: |weblate_widget|

68
tutorials/2d/2d_lights_and_shadows.rst
View File

@ -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 <https://developer.nvidia.com/gpugems/GPUGems/gpugems_ch11.html>`_
To give the shadows that nice, soft edge look we set the variables `filter`, `filter smooth`, and
`gradient length`. Godot supports `Percentage Closer Filtering <https://developer.nvidia.com/gpugems/GPUGems/gpugems_ch11.html>`_
(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.

12
tutorials/2d/2d_meshes.rst
View File

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

24
tutorials/2d/2d_movement.rst
View File

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

34
tutorials/2d/2d_sprite_animation.rst
View File

@ -43,7 +43,7 @@ with the following nodes:
`Physics Introduction <doc_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.

2
tutorials/2d/2d_transforms.rst
View File

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

54
tutorials/2d/custom_drawing_in_2d.rst
View File

@ -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<class_CanvasItem_method_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<class_CanvasItem_method_draw_polygon>`.
As a workaround, install and use the
`Antialiased Line2D add-on <https://github.com/godot-extended-libraries/godot-antialiased-line2d>`__
(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
-----

44
tutorials/2d/particle_systems_2d.rst
View File

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

24
tutorials/2d/using_tilemaps.rst
View File

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

14
tutorials/3d/baked_lightmaps.rst
View File

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

16
tutorials/3d/csg_tools.rst
View File

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

10
tutorials/3d/environment_and_post_processing.rst
View File

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

18
tutorials/3d/gi_probes.rst
View File

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

10
tutorials/3d/lights_and_shadows.rst
View File

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

16
tutorials/3d/occluders.rst
View File

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

18
tutorials/3d/portals/advanced_room_and_portal_usage.rst
View File

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

52
tutorials/3d/portals/editing_rooms_and_portals.rst
View File

@ -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<class_RoomGroup>` to denote an outside area.
- The `MeshInstance<class_MeshInstance>`\ s inside the `Room<class_Room>`\ s are either ``STATIC`` or ``DYNAMIC``.
- We have created a `Spatial<class_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<class_MeshInstance>`\ s inside the `Room<class_Room>`\ s are either `STATIC` or `DYNAMIC`.
- We have created a `Spatial<class_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<class_Room>`.
- ``-roomgroup`` becomes a `RoomGroup<class_RoomGroup>`.
- ``-portal`` becomes a `Portal<class_Portal>`.
- ``-bound`` becomes a manual bound.
- `-room` becomes a `Room<class_Room>`.
- `-roomgroup` becomes a `RoomGroup<class_RoomGroup>`.
- `-portal` becomes a `Portal<class_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<class_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
~~~~~~~~~~~

8
tutorials/3d/portals/first_steps_with_rooms_and_portals.rst
View File

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

20
tutorials/3d/portals/rooms_and_portals_example.rst
View File

@ -20,7 +20,7 @@ Step 1
- Next add a `RoomManager<class_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<class_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<class_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<class_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<class_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.

Some files were not shown because too many files have changed in this diff Show More