diff --git a/.gitignore b/.gitignore index e3642b897..c732858ee 100644 --- a/.gitignore +++ b/.gitignore @@ -36,3 +36,7 @@ ehthumbs_vista.db $RECYCLE.BIN/ logo.h *.autosave + +# Output of list-unused-images.sh tool +tmp-unused-images +tmp-unused-images-history diff --git a/.travis.yml b/.travis.yml index 6d2f840c2..51281c256 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,12 +1,12 @@ os: linux dist: bionic -language: python +language: python - "3.8" -python: - - "3.8" - -stages: - - build +env: + global: + - SPHINX_NO_GDSCRIPT=1 + - SPHINX_NO_SEARCH=1 + - SPHINX_NO_DESCRIPTIONS=1 matrix: include: @@ -18,16 +18,17 @@ matrix: packages: - dos2unix - recode - - texlive-full + +install: + - pip install -r requirements.txt + - pip install codespell script: - - bash ./format.sh + - bash _tools/format.sh # Check for possible typos - - pip install codespell - - codespell -I codespell-ignore.txt {about,community,development,getting_started,tutorials}/**/*.rst + - codespell -I _tools/codespell-ignore.txt {about,community,development,getting_started,tutorials}/**/*.rst - - pip install -r requirements.txt # TODO: Add `-W` to turn warnings into errors. # This can only be done once all warnings have been fixed. - - sphinx-build --color -b html -d _build/doctrees . _build/html + - sphinx-build --color -b dummy -d _build/doctrees . _build/html diff --git a/Makefile b/Makefile index 2315518cb..dabd23408 100644 --- a/Makefile +++ b/Makefile @@ -52,6 +52,7 @@ help: @echo " linkcheck to check all external links for integrity" @echo " doctest to run all doctests embedded in the documentation (if enabled)" @echo " coverage to run coverage check of the documentation (if enabled)" + @echo " dummy to run only the parse steps without generating output" clean: rm -rf $(BUILDDIR)/* @@ -195,3 +196,8 @@ pseudoxml: $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml @echo @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." + +dummy: + $(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. No output." diff --git a/_static/css/custom.css b/_static/css/custom.css index 528222fc7..713d9a11c 100644 --- a/_static/css/custom.css +++ b/_static/css/custom.css @@ -48,6 +48,7 @@ --search-credits-link-color: #4392c5; /* derived from --link-color */ --highlight-background-color: #f5ffe1; + --highlight-background-emph-color: #dbe6c3; --highlight-default-color: #404040; --highlight-comment-color: #408090; --highlight-keyword-color: #007020; @@ -133,6 +134,7 @@ /* Colors taken from the Godot script editor with the Adaptive theme */ --highlight-background-color: #202531; + --highlight-background-emph-color: #2d3444; --highlight-default-color: rgba(255, 255, 255, 0.85); --highlight-comment-color: rgba(204, 206, 211, 0.5); --highlight-keyword-color: #ff7085; @@ -190,7 +192,7 @@ legend, .rst-content .toctree-wrapper p.caption, .rst-versions { /* Use a system font stack for better performance (no Web fonts required) */ - font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif; + font-family: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; } h1, @@ -536,6 +538,11 @@ code, background-color: var(--highlight-background-color); } +/* Emphasized lines */ +.highlight .hll { + background-color: var(--highlight-background-emph-color); +} + .highlight .gh /* Generic.Heading */, .highlight .gu /* Generic.Subheading */, .highlight .go /* Generic.Output */, diff --git a/codespell-ignore.txt b/_tools/codespell-ignore.txt similarity index 100% rename from codespell-ignore.txt rename to _tools/codespell-ignore.txt diff --git a/format.sh b/_tools/format.sh similarity index 100% rename from format.sh rename to _tools/format.sh diff --git a/_tools/list-unused-images.sh b/_tools/list-unused-images.sh new file mode 100644 index 000000000..44c70f6d4 --- /dev/null +++ b/_tools/list-unused-images.sh @@ -0,0 +1,40 @@ +#!/bin/bash + +check_git_history=false + +rm -f tmp-unused-images +rm -f tmp-unused-images-history + +# List images which might be unused. +# Exceptions are ignored, and for .svg files we also look for potential .png +# files with the same base name, as they might be sources. + +exceptions="docs_logo.png tween_cheatsheet.png" + +files=$(find -name "_build" -prune -o \( -name "*.png" -o -name "*.jpg" -o -name "*.svg" -o -name "*.gif" \) -print | sort) + +for path in $files; do + file=$(basename $path) + if echo "$exceptions" | grep -q "$file"; then + continue + fi + ext=${file##*.} + base=${file%.*} + found=$(rg -l ":: .*[ /]$file") + if [ -z "$found" -a "$ext" == "svg" ]; then + # May be source file. + found=$(rg -l ":: .*[ /]$base.png") + fi + if [ -z "$found" ]; then + echo "$path" >> tmp-unused-images + fi +done + + +if [ "$check_git_history" = true ]; then + for file in $(cat tmp-unused-images); do + echo "File: $file" + git log --diff-filter=A --follow $file + echo + done > tmp-unused-images-history +fi diff --git a/conf.py b/conf.py index 24def6f1c..60af3f0b6 100644 --- a/conf.py +++ b/conf.py @@ -13,13 +13,24 @@ needs_sphinx = "1.3" # Sphinx extension module names and templates location sys.path.append(os.path.abspath("_extensions")) extensions = [ - "gdscript", - "godot_descriptions", - "sphinx_search.extension", "sphinx_tabs.tabs", "sphinx.ext.imgmath", ] +# Warning when the Sphinx Tabs extension is used with unknown +# builders (like the dummy builder) - as it doesn't cause errors, +# we can ignore this so we still can treat other warnings as errors. +sphinx_tabs_nowarn = True + +if not os.getenv("SPHINX_NO_GDSCRIPT"): + extensions.append("gdscript") + +if not os.getenv("SPHINX_NO_SEARCH"): + extensions.append("sphinx_search.extension") + +if not os.getenv("SPHINX_NO_DESCRIPTIONS"): + extensions.append("godot_descriptions") + templates_path = ["_templates"] # You can specify multiple suffix as a list of string: ['.rst', '.md'] @@ -181,9 +192,42 @@ linkcheck_timeout = 10 # -- I18n settings -------------------------------------------------------- +# Godot localization is handled via https://github.com/godotengine/godot-docs-l10n +# where the main docs repo is a submodule. Therefore the translated material is +# actually in the parent folder of this conf.py, hence the "../". + locale_dirs = ["../sphinx/po/"] gettext_compact = False +# We want to host the localized images in godot-docs-l10n, but Sphinx does not provide +# the necessary feature to do so. `figure_language_filename` has `{root}` and `{path}`, +# but they resolve to (host) absolute paths, so we can't use them as is to access "../". +# However, Python is glorious and lets us redefine Sphinx's internal method that handles +# `figure_language_filename`, so we do our own post-processing to fix the absolute path +# and point to the parallel folder structure in godot-docs-l10n. +# Note: Sphinx's handling of `figure_language_filename` may change in the future, monitor +# https://github.com/sphinx-doc/sphinx/issues/7768 to see what would be relevant for us. +figure_language_filename = "{root}.{language}{ext}" + +import sphinx +cwd = os.getcwd() + +sphinx_original_get_image_filename_for_language = sphinx.util.i18n.get_image_filename_for_language + +def godot_get_image_filename_for_language(filename, env): + """ + Hack the absolute path returned by Sphinx based on `figure_language_filename` + to insert our `../images` relative path to godot-docs-l10n's images folder, + which mirrors the folder structure of the docs repository. + The returned string should also be absolute so that `os.path.exists` can properly + resolve it when trying to concatenate with the original doc folder. + """ + path = sphinx_original_get_image_filename_for_language(filename, env) + path = os.path.abspath(os.path.join("../images/", os.path.relpath(path, cwd))) + return path + +sphinx.util.i18n.get_image_filename_for_language = godot_get_image_filename_for_language + # Couldn't find a way to retrieve variables nor do advanced string # concat from reST, so had to hardcode this in the "epilog" added to # all pages. This is used in index.rst to display the Weblate badge. diff --git a/development/compiling/compiling_for_x11.rst b/development/compiling/compiling_for_x11.rst index d3001b1da..58e5db14b 100644 --- a/development/compiling/compiling_for_x11.rst +++ b/development/compiling/compiling_for_x11.rst @@ -51,7 +51,7 @@ Distro-specific one-liners | | | | | sudo dnf install scons pkgconfig libX11-devel libXcursor-devel libXrandr-devel libXinerama-devel \ | | | libXi-devel mesa-libGL-devel mesa-libGLU-devel alsa-lib-devel pulseaudio-libs-devel \ | -| | libudev-devel yasm | +| | libudev-devel yasm gcc-c++ | +------------------+-----------------------------------------------------------------------------------------------------------+ | **FreeBSD** | :: | | | | diff --git a/development/compiling/compiling_with_mono.rst b/development/compiling/compiling_with_mono.rst index 6a37dda15..cf4c1e6b2 100644 --- a/development/compiling/compiling_with_mono.rst +++ b/development/compiling/compiling_with_mono.rst @@ -11,16 +11,18 @@ Requirements - Mono 5.12.0 or greater - MSBuild - NuGet -- pkg-config +- **On Linux/macOS only:** pkg-config You may need to import necessary certificates for NuGet to perform HTTPS requests. The recommended method is to use **curl**'s CA (Certificate Autorities) certificate bundle. -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):: +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):: + # If using PowerShell, replace `curl` with `curl.exe` below. curl -LO https://curl.haxx.se/ca/cacert.pem cert-sync --user cacert.pem @@ -45,7 +47,7 @@ By default, the Mono module is disabled when building. To enable it, add the option ``module_mono_enabled=yes`` to the SCons command line. 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 @@ -76,6 +78,7 @@ generate the Mono glue. Notes ^^^^^ + - **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 @@ -121,6 +124,7 @@ Examples Example (Windows) ^^^^^^^^^^^^^^^^^ + :: # Build temporary binary @@ -137,6 +141,7 @@ Example (Windows) Example (X11) ^^^^^^^^^^^^^ + :: # Build temporary binary @@ -188,7 +193,7 @@ inside the ZIP archive: +-------------------------------------------------------+---------------------------------------------------------------+ Editor -^^^^^^^^ +^^^^^^ The name of the data directory for the Godot editor will always be ``GodotSharp``. The contents of this directory are the following: diff --git a/development/cpp/configuring_an_ide/img/kdevelop_openproject.png b/development/cpp/configuring_an_ide/img/kdevelop_openproject.png deleted file mode 100644 index c41a363ca..000000000 Binary files a/development/cpp/configuring_an_ide/img/kdevelop_openproject.png and /dev/null differ diff --git a/development/cpp/configuring_an_ide/visual_studio_code.rst b/development/cpp/configuring_an_ide/visual_studio_code.rst index 2f6281d96..79b944ac9 100644 --- a/development/cpp/configuring_an_ide/visual_studio_code.rst +++ b/development/cpp/configuring_an_ide/visual_studio_code.rst @@ -3,7 +3,7 @@ Visual Studio Code ================== -`Visual Studio Code `_ is a free cross-platform IDE +`Visual Studio Code `_ is a free cross-platform IDE by `Microsoft `_ (not to be confused with :ref:`doc_configuring_an_ide_vs`). Importing the project @@ -51,7 +51,7 @@ Importing the project An example of a filled out ``tasks.json``. -Arguments are can be different based on your own setup and needs. See +Arguments can be different based on your own setup and needs. See :ref:`doc_introduction_to_the_buildsystem` for a full list of arguments. Debugging the project @@ -75,9 +75,11 @@ To run and debug the project you need to create a new configuration in the ``lau "name": "Launch", "type": "cppdbg", "request": "launch", + // Change the path below to match your current platform. "program": "${workspaceFolder}/bin/godot.x11.tools.64", - // Change to your current platform - "args": [ "-e" ], + // Change the arguments below for the project you want to test with. + // To run the project instead of editing it, remove the "--editor" argument. + "args": [ "--editor", "--path", "path-to-your-godot-project-folder" ], "stopAtEntry": false, "cwd": "${workspaceFolder}", "environment": [], diff --git a/img/architecture_diagram.jpg b/development/cpp/img/architecture_diagram.jpg similarity index 100% rename from img/architecture_diagram.jpg rename to development/cpp/img/architecture_diagram.jpg diff --git a/development/cpp/introduction_to_godot_development.rst b/development/cpp/introduction_to_godot_development.rst index e1371aaf8..fc3c7da7a 100644 --- a/development/cpp/introduction_to_godot_development.rst +++ b/development/cpp/introduction_to_godot_development.rst @@ -14,7 +14,7 @@ The following diagram describes the architecture used by Godot, from the core components down to the abstracted drivers, via the scene structure and the servers. -.. image:: /img/architecture_diagram.jpg +.. image:: img/architecture_diagram.jpg Debugging the editor with gdb ----------------------------- diff --git a/getting_started/editor/command_line_tutorial.rst b/getting_started/editor/command_line_tutorial.rst index 5a014c762..b86b6391b 100644 --- a/getting_started/editor/command_line_tutorial.rst +++ b/getting_started/editor/command_line_tutorial.rst @@ -277,11 +277,11 @@ instead of ``--export``. Their parameters and usage are the same. Running a script ---------------- -It is possible to run a simple .gd script from the command line. This -feature is especially useful in large projects, for batch +It is possible to run a simple ``.gd`` script from the command line. +This feature is especially useful in large projects, e.g. for batch conversion of assets or custom import/export. -The script must inherit from SceneTree or MainLoop. +The script must inherit from ``SceneTree`` or ``MainLoop``. Here is a simple example of how it works: @@ -301,5 +301,5 @@ And how to run it: # Prints "Hello!" to standard output. godot -s sayhello.gd -If no project.godot exists at the path, current path is assumed to be the -current working directory (unless ``-path`` is specified). +If no ``project.godot`` exists at the path, current path is assumed to be the +current working directory (unless ``--path`` is specified). diff --git a/getting_started/scripting/gdscript/gdscript_exports.rst b/getting_started/scripting/gdscript/gdscript_exports.rst index 6febf17f9..b81011086 100644 --- a/getting_started/scripting/gdscript/gdscript_exports.rst +++ b/getting_started/scripting/gdscript/gdscript_exports.rst @@ -158,6 +158,13 @@ has value 4 and ``Wind`` corresponds to value 8. Usually, constants should be defined accordingly (e.g. ``const ELEMENT_WIND = 8`` and so on). +Export hints are also provided for the physics and render layers defined in the project settings:: + + export(int, LAYERS_2D_PHYSICS) var layers_2d_physics + export(int, LAYERS_2D_RENDER) var layers_2d_render + export(int, LAYERS_3D_PHYSICS) var layers_3d_physics + export(int, LAYERS_3D_RENDER) var layers_3d_render + Using bit flags requires some understanding of bitwise operations. If in doubt, boolean variables should be exported instead. diff --git a/getting_started/scripting/gdscript/img/typed_gdscript_code_completion.png b/getting_started/scripting/gdscript/img/typed_gdscript_code_completion.png deleted file mode 100644 index 0d3858dfd..000000000 Binary files a/getting_started/scripting/gdscript/img/typed_gdscript_code_completion.png and /dev/null differ diff --git a/getting_started/scripting/gdscript/img/typed_gdscript_warnings03.png b/getting_started/scripting/gdscript/img/typed_gdscript_warnings03.png deleted file mode 100644 index ba167fad4..000000000 Binary files a/getting_started/scripting/gdscript/img/typed_gdscript_warnings03.png and /dev/null differ diff --git a/getting_started/scripting/gdscript/static_typing.rst b/getting_started/scripting/gdscript/static_typing.rst index d1351987c..64271c127 100644 --- a/getting_started/scripting/gdscript/static_typing.rst +++ b/getting_started/scripting/gdscript/static_typing.rst @@ -59,14 +59,14 @@ options for a class called ``PlayerController``. You've probably stored a node in a variable before, and typed a dot to be left with no autocomplete suggestions: -.. figure:: ./img/typed_gdscript_code_completion_dynamic.png +.. figure:: img/typed_gdscript_code_completion_dynamic.png :alt: code completion options for dynamic This is due to dynamic code. Godot cannot know what node or value type you're passing to the function. If you write the type explicitly however, you will get all public methods and variables from the node: -.. figure:: ./img/typed_gdscript_code_completion_typed.png +.. figure:: img/typed_gdscript_code_completion_typed.png :alt: code completion options for typed In the future, typed GDScript will also increase code performance: @@ -200,7 +200,7 @@ node: ``($Timer as Timer)``, ``($Player as KinematicBody2D)``, etc. Godot will ensure the type works and if so, the line number will turn green at the left of the script editor. -.. figure:: ./img/typed_gdscript_safe_unsafe_line.png +.. figure:: img/typed_gdscript_safe_unsafe_line.png :alt: Unsafe vs Safe Line Unsafe line (line 7) vs Safe Lines (line 6 and 8) diff --git a/getting_started/scripting/gdscript/warning_system.rst b/getting_started/scripting/gdscript/warning_system.rst index 24dc92d30..04ec94399 100644 --- a/getting_started/scripting/gdscript/warning_system.rst +++ b/getting_started/scripting/gdscript/warning_system.rst @@ -11,7 +11,7 @@ to runtime errors. You can configure warnings in the Project Settings under the section called **Gdscript**: -.. figure:: ./img/typed_gdscript_warning_system_settings.png +.. figure:: img/typed_gdscript_warning_system_settings.png :alt: Warning system project settings Warning system project settings @@ -19,7 +19,7 @@ called **Gdscript**: You can find a list of warnings for the active GDScript file in the script editor's status bar. The example below has 3 warnings: -.. figure:: ./img/typed_gdscript_warning_example.png +.. figure:: img/typed_gdscript_warning_example.png :alt: Warning system example Warning system example @@ -30,7 +30,7 @@ right of the warning's description. Godot will add a comment above the corresponding line and the code won't trigger the corresponding warning anymore: -.. figure:: ./img/typed_gdscript_warning_system_ignore.png +.. figure:: img/typed_gdscript_warning_system_ignore.png :alt: Warning system ignore example Warning system ignore example @@ -45,7 +45,7 @@ all warnings. Head to the ``GDScript`` section of the Project Settings to turn on this option. Here's the same file as the previous example with warnings as errors turned on: -.. figure:: ./img/typed_gdscript_warning_system_errors.png +.. figure:: img/typed_gdscript_warning_system_errors.png :alt: Warnings as errors Warnings as errors diff --git a/getting_started/step_by_step/filesystem.rst b/getting_started/step_by_step/filesystem.rst index b3d53214a..a79adc0e1 100644 --- a/getting_started/step_by_step/filesystem.rst +++ b/getting_started/step_by_step/filesystem.rst @@ -21,9 +21,9 @@ included. If a resource has sub-resources that are built-in, the resource is saved in a single file together with all the bundled sub-resources. For example, a font resource is often bundled together with the font textures. -The Godot file system avoids using metadata files. Existing asset managers and VCSs are better than -anything we can implement, so Godot tries its best to play along with SVN, -Git, Mercurial, Perforce, etc. +The Godot file system avoids using metadata files. Existing asset managers and VCSs +are better than anything we can implement, so Godot tries its best to play along +with SVN, Git, Mercurial, Perforce, etc. Example of file system contents: @@ -38,21 +38,21 @@ Example of file system contents: project.godot ------------- -The project.godot file is the project description file, and it is always found at -the root of the project. In fact, its location defines where the root is. This +The ``project.godot`` file is the project description file, and it is always found +at the root of the project. In fact, its location defines where the root is. This is the first file that Godot looks for when opening a project. This file contains the project configuration in plain text, using the win.ini -format. Even an empty project.godot can function as a basic definition of a blank -project. +format. Even an empty ``project.godot`` can function as a basic definition of +a blank project. Path delimiter -------------- Godot only supports ``/`` as a path delimiter. This is done for portability reasons. All operating systems support this, even Windows, -so a path such as ``c:\project\project.godot`` needs to be typed as -``c:/project/project.godot``. +so a path such as ``C:\project\project.godot`` needs to be typed as +``C:/project/project.godot``. Resource path ------------- @@ -62,7 +62,7 @@ cumbersome and non-portable. To solve this problem, the special path ``res://`` was created. The path ``res://`` will always point at the project root (where -project.godot is located, so ``res://project.godot`` is always +``project.godot`` is located, so ``res://project.godot`` is always valid). This file system is read-write only when running the project locally from @@ -73,9 +73,11 @@ read-only and writing will no longer be permitted. User path --------- -Writing to disk is still needed for tasks such as saving game -state or downloading content packs. To this end, the engine ensures that there is a -special path ``user://`` that is always writable. +Writing to disk is still needed for tasks such as saving game state or +downloading content packs. To this end, the engine ensures that there is a +special path ``user://`` that is always writable. This path resolves +differently depending on the OS the project is running on. Local path +resolution is further explained in :ref:`doc_data_paths`. Host file system ---------------- @@ -93,14 +95,14 @@ moving assets around (renaming them or moving them from one path to another insi the project) will break existing references to these assets. These references will have to be re-defined to point at the new asset location. -To avoid this, do all your move, delete and rename operations from within Godot, on the FileSystem -dock. Never move assets from outside Godot, or dependencies will have to be -fixed manually (Godot detects this and helps you fix them anyway, but why +To avoid this, do all your move, delete and rename operations from within Godot, on +the FileSystem dock. Never move assets from outside Godot, or dependencies will have +to be fixed manually (Godot detects this and helps you fix them anyway, but why go the hard route?). The second is that, under Windows and macOS, file and path names are case insensitive. -If a developer working in a case insensitive host file system saves an asset as "myfile.PNG", -but then references it as "myfile.png", it will work fine on their platform, but not +If a developer working in a case insensitive host file system saves an asset as ``myfile.PNG``, +but then references it as ``myfile.png``, it will work fine on their platform, but not on other platforms, such as Linux, Android, etc. This may also apply to exported binaries, which use a compressed package to store all files. diff --git a/getting_started/step_by_step/godot_design_philosophy.rst b/getting_started/step_by_step/godot_design_philosophy.rst index 9d6b8e919..a65a9df4e 100644 --- a/getting_started/step_by_step/godot_design_philosophy.rst +++ b/getting_started/step_by_step/godot_design_philosophy.rst @@ -170,9 +170,9 @@ base unit for 2D scenes is pixels.** Even though the engines are separate, you can render 2D in 3D, 3D in 2D, and overlay 2D sprites and interfaces over your 3D world. -.. |image0| image:: ./img/engine_design_01.png -.. |image1| image:: ./img/engine_design_02.png -.. |image2| image:: ./img/engine_design_03.png -.. |image3| image:: ./img/engine_design_visual_script.png -.. |image4| image:: ./img/engine_design_fsm_plugin.png -.. |image5| image:: ./img/engine_design_rpg_in_a_box.png +.. |image0| image:: img/engine_design_01.png +.. |image1| image:: img/engine_design_02.png +.. |image2| image:: img/engine_design_03.png +.. |image3| image:: img/engine_design_visual_script.png +.. |image4| image:: img/engine_design_fsm_plugin.png +.. |image5| image:: img/engine_design_rpg_in_a_box.png diff --git a/getting_started/step_by_step/img/addglobal.png b/getting_started/step_by_step/img/addglobal.png deleted file mode 100644 index f62e4baa6..000000000 Binary files a/getting_started/step_by_step/img/addglobal.png and /dev/null differ diff --git a/img/brainslug.jpg b/getting_started/step_by_step/img/brainslug.jpg similarity index 100% rename from img/brainslug.jpg rename to getting_started/step_by_step/img/brainslug.jpg diff --git a/getting_started/step_by_step/img/clearcolor.png b/getting_started/step_by_step/img/clearcolor.png deleted file mode 100644 index ceb2a428b..000000000 Binary files a/getting_started/step_by_step/img/clearcolor.png and /dev/null differ diff --git a/getting_started/step_by_step/img/color_gradient_ui.png b/getting_started/step_by_step/img/color_gradient_ui.png deleted file mode 100644 index 961f27842..000000000 Binary files a/getting_started/step_by_step/img/color_gradient_ui.png and /dev/null differ diff --git a/getting_started/step_by_step/img/ctrl_normal.png b/getting_started/step_by_step/img/ctrl_normal.png deleted file mode 100644 index dcbe38330..000000000 Binary files a/getting_started/step_by_step/img/ctrl_normal.png and /dev/null differ diff --git a/getting_started/step_by_step/img/ctrl_tapped.png b/getting_started/step_by_step/img/ctrl_tapped.png deleted file mode 100644 index 1fd4191bc..000000000 Binary files a/getting_started/step_by_step/img/ctrl_tapped.png and /dev/null differ diff --git a/getting_started/step_by_step/img/draw_path2d.png b/getting_started/step_by_step/img/draw_path2d.png deleted file mode 100644 index 7d6011646..000000000 Binary files a/getting_started/step_by_step/img/draw_path2d.png and /dev/null differ diff --git a/getting_started/step_by_step/img/export_project_override.png b/getting_started/step_by_step/img/export_project_override.png deleted file mode 100644 index d1e63af8d..000000000 Binary files a/getting_started/step_by_step/img/export_project_override.png and /dev/null differ diff --git a/getting_started/step_by_step/img/gui_step_tutorial_inherited_scene_parent.png b/getting_started/step_by_step/img/gui_step_tutorial_inherited_scene_parent.png deleted file mode 100644 index 0171cef11..000000000 Binary files a/getting_started/step_by_step/img/gui_step_tutorial_inherited_scene_parent.png and /dev/null differ diff --git a/getting_started/step_by_step/img/importproject.png b/getting_started/step_by_step/img/importproject.png deleted file mode 100644 index b9d1f9cc6..000000000 Binary files a/getting_started/step_by_step/img/importproject.png and /dev/null differ diff --git a/getting_started/step_by_step/img/inputmap.png b/getting_started/step_by_step/img/inputmap.png deleted file mode 100644 index 762565d7e..000000000 Binary files a/getting_started/step_by_step/img/inputmap.png and /dev/null differ diff --git a/getting_started/step_by_step/img/load_mob_scene.png b/getting_started/step_by_step/img/load_mob_scene.png deleted file mode 100644 index d7359496f..000000000 Binary files a/getting_started/step_by_step/img/load_mob_scene.png and /dev/null differ diff --git a/getting_started/step_by_step/img/particle_trail_settings.png b/getting_started/step_by_step/img/particle_trail_settings.png deleted file mode 100644 index 6560d7862..000000000 Binary files a/getting_started/step_by_step/img/particle_trail_settings.png and /dev/null differ diff --git a/getting_started/step_by_step/img/particle_trail_settings2.png b/getting_started/step_by_step/img/particle_trail_settings2.png deleted file mode 100644 index 0ad3ef67b..000000000 Binary files a/getting_started/step_by_step/img/particle_trail_settings2.png and /dev/null differ diff --git a/getting_started/step_by_step/img/pong_layout.png b/getting_started/step_by_step/img/pong_layout.png deleted file mode 100644 index 7c626cd64..000000000 Binary files a/getting_started/step_by_step/img/pong_layout.png and /dev/null differ diff --git a/getting_started/step_by_step/img/pong_nodes.png b/getting_started/step_by_step/img/pong_nodes.png deleted file mode 100644 index e30d77ba2..000000000 Binary files a/getting_started/step_by_step/img/pong_nodes.png and /dev/null differ diff --git a/getting_started/step_by_step/img/singlecontrol.png b/getting_started/step_by_step/img/singlecontrol.png deleted file mode 100644 index 88b6071e9..000000000 Binary files a/getting_started/step_by_step/img/singlecontrol.png and /dev/null differ diff --git a/getting_started/step_by_step/img/ui_gui_containers_structure.png b/getting_started/step_by_step/img/ui_gui_containers_structure.png deleted file mode 100644 index 6fe7d79a2..000000000 Binary files a/getting_started/step_by_step/img/ui_gui_containers_structure.png and /dev/null differ diff --git a/getting_started/step_by_step/img/ui_texturerect_load_texture_951x540.png b/getting_started/step_by_step/img/ui_texturerect_load_texture_951x540.png deleted file mode 100644 index e9882f123..000000000 Binary files a/getting_started/step_by_step/img/ui_texturerect_load_texture_951x540.png and /dev/null differ diff --git a/getting_started/step_by_step/scripting.rst b/getting_started/step_by_step/scripting.rst index 73605ab10..6c17ba38d 100644 --- a/getting_started/step_by_step/scripting.rst +++ b/getting_started/step_by_step/scripting.rst @@ -170,7 +170,7 @@ as well as how it interacts with other nodes: children, parent, siblings, and so on. The local scope of the script is the node. In other words, the script inherits the functions provided by that node. -.. image:: /img/brainslug.jpg +.. image:: img/brainslug.jpg .. _doc_scripting_handling_a_signal: diff --git a/getting_started/step_by_step/ui_code_a_life_bar.rst b/getting_started/step_by_step/ui_code_a_life_bar.rst index dfa0123a0..37bc29e37 100644 --- a/getting_started/step_by_step/ui_code_a_life_bar.rst +++ b/getting_started/step_by_step/ui_code_a_life_bar.rst @@ -25,8 +25,8 @@ You will learn: If you want to learn how to set up the interface instead, check out the step-by-step UI tutorials: -- Create a main menu screen -- Create a game user interface +- :doc:`ui_main_menu` +- :doc:`ui_game_user_interface` When you code a game, you want to build the core gameplay first: the @@ -405,7 +405,7 @@ clear its content. Let's animate the ``animated_health`` value. Call the .. code-tab:: gdscript GDScript func update_health(new_value): - tween.interpolate_property(self, "animated_health", animated_health, new_value, 0.6, Tween.TRANS_LINEAR, Tween.EASE_IN) + tween.interpolate_property(self, "animated_health", animated_health, new_value, 0.6) .. code-tab:: csharp @@ -438,15 +438,6 @@ of the animation is the ``Player``'s ``health`` after the ``health_changed``: that's ``new_value``. And ``0.6`` is the animation's duration in seconds. -:: - - ... 0.6, Tween.TRANS_LINEAR, Tween.EASE_IN) - -The last two arguments are constants from the ``Tween`` class. -``TRANS_LINEAR`` means the animation should be linear. ``EASE_IN`` -doesn't do anything with a linear transition, but we must provide this -last argument or we'll get an error. - The animation will not play until we activated the ``Tween`` node with ``tween.start()``. We only have to do this once if the node is not active. Add this code after the last line: @@ -480,7 +471,7 @@ So far, the update\_health method looks like this: .. code-tab:: gdscript GDScript func update_health(new_value): - tween.interpolate_property(self, "animated_health", animated_health, new_value, 0.6, Tween.TRANS_LINEAR, Tween.EASE_IN) + tween.interpolate_property(self, "animated_health", animated_health, new_value, 0.6) if not tween.is_active(): tween.start() @@ -644,7 +635,7 @@ We then have to call the ``interpolate_property`` method of the .. tabs:: .. code-tab:: gdscript GDScript - tween.interpolate_property(self, "modulate", start_color, end_color, 1.0, Tween.TRANS_LINEAR, Tween.EASE_IN) + tween.interpolate_property(self, "modulate", start_color, end_color, 1.0) .. code-tab:: csharp @@ -653,8 +644,7 @@ We then have to call the ``interpolate_property`` method of the This time, we change the ``modulate`` property and have it animate from ``start_color`` to the ``end_color``. The duration is of one second, -with a linear transition. Here again, because the transition is linear, -the easing does not matter. Here's the complete ``_on_Player_died`` +with a linear transition. Here's the complete ``_on_Player_died`` method: .. tabs:: @@ -663,7 +653,7 @@ method: func _on_Player_died(): var start_color = Color(1.0, 1.0, 1.0, 1.0) var end_color = Color(1.0, 1.0, 1.0, 0.0) - tween.interpolate_property(self, "modulate", start_color, end_color, 1.0, Tween.TRANS_LINEAR, Tween.EASE_IN) + tween.interpolate_property(self, "modulate", start_color, end_color, 1.0) .. code-tab:: csharp diff --git a/getting_started/step_by_step/ui_game_user_interface.rst b/getting_started/step_by_step/ui_game_user_interface.rst index 97e6feb68..41ebb8a4f 100644 --- a/getting_started/step_by_step/ui_game_user_interface.rst +++ b/getting_started/step_by_step/ui_game_user_interface.rst @@ -8,7 +8,7 @@ game Graphical User Interface (GUI) with reusable UI components: a life bar, an energy bar, and bomb and emerald counters. By the end of this tutorial, you'll have a game GUI, ready to control with GDscript or VisualScript: -.. figure:: ./img/ui_gui_design_final_result.png +.. figure:: img/ui_gui_design_final_result.png The final result @@ -48,7 +48,7 @@ of one another inside a ``VBoxContainer``. And we'll need a last ``HBoxContainer`` in the right column to place the bomb and emerald counters side-by-side. -.. figure:: ./img/ui_gui_step_tutorial_containers_structure.png +.. figure:: img/ui_gui_step_tutorial_containers_structure.png We get a clean UI layout with only 4 containers @@ -90,7 +90,7 @@ Add a ``VBoxContainer`` as a child of ``HBoxContainer`` and name it ``Bars``. Se ``HBoxContainer`` again and this time, add another ``HBoxContainer`` as a child of it. Call it ``Counters``. With these four containers, we have the base for our GUI scene. -.. figure:: ./img/ui_gui_containers_structure_in_godot.png +.. figure:: img/ui_gui_containers_structure_in_godot.png You should have 4 containers that look like this @@ -127,7 +127,7 @@ Name it ``Count``. Inside of it, add three nodes: To add the nodes as siblings, always select the ``Count`` node first. -.. figure:: ./img/ui_gui_step_tutorial_bar_template_1.png +.. figure:: img/ui_gui_step_tutorial_bar_template_1.png Your scene tree should look like this. We're ready to throw in some textures @@ -136,7 +136,7 @@ Our scene is still empty. It's time to throw in some textures. To load the textures, head to the FileSystem dock to the left of the viewport. Browse down to the res://assets/GUI folder. -.. figure:: ./img/ui_gui_step_tutorial_textures_in_FileSystem_tab.png +.. figure:: img/ui_gui_step_tutorial_textures_in_FileSystem_tab.png You should see a list of textures that we'll use to skin our interface. @@ -156,7 +156,7 @@ the ``Text`` property and type ``10``. This way, we can see both nodes in the viewport. They should stack up in the top-left corner of their parent ``MarginContainer``. -.. figure:: ./img/ui_gui_step_tutorial_bar_label_stacked.png +.. figure:: img/ui_gui_step_tutorial_bar_label_stacked.png If you select both nodes, you should see something like this @@ -174,7 +174,7 @@ them inside a regular Control or another UI element. We'll use the the ``Title`` and ``Number``, and drag and drop them onto ``Background``. -.. figure:: ./img/ui_gui_step_tutorial_bar_nesting_inside_background.png +.. figure:: img/ui_gui_step_tutorial_bar_nesting_inside_background.png By using the Background node as the two textures' parent, we take control away from the Count MarginContainer @@ -190,7 +190,7 @@ text should snap to the center of the ``Background``'s right edge. Resize the node horizontally, so it takes the right half of the ``Background`` and there's a bit of padding with the right edge. -.. figure:: ./img/ui_gui_step_tutorial_bar_placed_title_and_label.png +.. figure:: img/ui_gui_step_tutorial_bar_placed_title_and_label.png Here's how the nodes' bounding boxes should look in the viewport. Keep it rough, you don't need to place them too precisely for now. @@ -222,7 +222,7 @@ baseline, click on the font field under the ``Custom Font`` category again and tweak the ``Bottom`` property until the text aligns with the ``Title`` node. I used a value of ``2`` pixels. -.. figure:: ./img/ui_gui_step_tutorial_number_baseline.png +.. figure:: img/ui_gui_step_tutorial_number_baseline.png With a Bottom value of 2 pixels, the Number aligns with the Title @@ -245,7 +245,7 @@ up. With only five ``Control`` nodes, our first bar is ready to use. -.. figure:: ./img/ui_gui_step_tutorial_bar_final.png +.. figure:: img/ui_gui_step_tutorial_bar_final.png That's it, our life bar is ready. This last part was quick, wasn't it? That's thanks to our robust container setup. @@ -268,7 +268,7 @@ number nodes. The ``Title`` node is a ``TextureRect``, so it's what we need to display the icon. In the scene tree, select the ``Title`` node, and rename it to ``Icon``. -.. figure:: ./img/ui_gui_step_tutorial_counter_design_1.png +.. figure:: img/ui_gui_step_tutorial_counter_design_1.png Here's how your node tree should look so far @@ -280,7 +280,7 @@ nodes. Click the Layout menu in the toolbar at the top of the viewport and select ``Full Rect``. Both nodes will update to fit the size of the ``Background``. -.. figure:: ./img/ui_gui_step_tutorial_counter_design_2.png +.. figure:: img/ui_gui_step_tutorial_counter_design_2.png The nodes anchor to the entire Background, but their position is off @@ -290,7 +290,7 @@ and center of the ``Background``. Select the ``Number`` node, change its resize its left edge a bit to add some padding between the left edge of the ``Background`` and the text. -.. figure:: ./img/ui_gui_step_tutorial_counter_design_3.png +.. figure:: img/ui_gui_step_tutorial_counter_design_3.png The Number node aligned to the left and centre @@ -308,7 +308,7 @@ the ``Background``'s right edge. Open the Layout menu again and select ``Center Right``. Move the icon up so it is centered vertically with the ``Background``. -.. figure:: ./img/ui_gui_step_tutorial_counter_design_4.png +.. figure:: img/ui_gui_step_tutorial_counter_design_4.png The bomb icon anchors to the Background's right edge. Resize the Counter container to see the Icon node stick to its right side @@ -326,7 +326,7 @@ can. Select the ``Bars`` node and scroll down to the ``Size Flags`` category. In the ``Horizontal`` category, check the ``Expand`` value. The ``Bars`` node should resize and push the counter to the right side of the screen. -.. figure:: ./img/ui_gui_step_tutorial_counter_design_5.png +.. figure:: img/ui_gui_step_tutorial_counter_design_5.png An expanding container eats all the space it can from its parent, pushing everything else along the way @@ -365,7 +365,7 @@ the one next to ``Bar`` to open the corresponding scene. Resize the and placed the Control nodes, we're ready to inherit this template and create the life bar. It's the same for the ``Counter``. -.. figure:: ./img/ui_gui_step_tutorial_bar_template_scene.png +.. figure:: img/ui_gui_step_tutorial_bar_template_scene.png With no extra changes, our Bar is ready to use @@ -456,7 +456,7 @@ will be affected by any property we change. You can try to change the size to a huge value like ``40`` and switch back to the ``LifeBar`` or the ``Bar`` scenes. You will see the text increased in size. -.. figure:: ./img/ui_gui_step_tutorial_design_EnergyBar_1.png +.. figure:: img/ui_gui_step_tutorial_design_EnergyBar_1.png If we change the font resource, all the nodes that use it are affected @@ -467,7 +467,7 @@ and screwdriver icon on the top right of the inspector. In the drop-down menu, select the ``Make Sub-Resources Unique`` option. Godot will find all the resources this node uses and create unique copies for us. -.. figure:: ./img/ui_gui_step_tutorial_design_EnergyBar_2.png +.. figure:: img/ui_gui_step_tutorial_design_EnergyBar_2.png Use this option to create unique copies of the resources for one node @@ -483,7 +483,7 @@ Scroll down to the ``Custom Font`` section and open ``Font``. Lower the adjust the ``Bottom`` spacing value to align the text's baseline with the EP label on the left. -.. figure:: ./img/ui_gui_step_tutorial_design_EnergyBar_3.png +.. figure:: img/ui_gui_step_tutorial_design_EnergyBar_3.png The EP Count widget, with a smaller font than its HP counterpart @@ -504,7 +504,7 @@ makes it a bit large. Select it and in the ``Rect`` section, change the automatically and the ``Title`` and ``Number`` nodes should reposition as well. -.. figure:: ./img/ui_gui_step_tutorial_design_EnergyBar_4.png +.. figure:: img/ui_gui_step_tutorial_design_EnergyBar_4.png The Count looks better now it's a bit smaller @@ -524,7 +524,7 @@ Let us now take care of the counters. Go to base. Rename the root node as ``BombCounter`` too. Save the new scene as ``BombCounter.tscn``. That's all for this scene. -.. figure:: ./img/ui_gui_step_tutorial_design_counters_1.png +.. figure:: img/ui_gui_step_tutorial_design_counters_1.png The bomb counter is the same as the original Counter scene @@ -539,7 +539,7 @@ Shift the emerald icon a bit to the right and down. Use the Arrow Keys on the keyboard to nudge its position. Save, and we're done with all the UI elements. -.. figure:: ./img/ui_gui_step_tutorial_design_counters_2.png +.. figure:: img/ui_gui_step_tutorial_design_counters_2.png The emerald counter should look something like this @@ -552,14 +552,14 @@ In the FileSystem dock, find the ``LifeBar.tscn`` and drag and drop it onto the ``Bars`` container in the scene tree. Do the same for the ``EnergyBar``. You should see them align vertically. -.. figure:: ./img/ui_gui_step_tutorial_assemble_final_gui_1.png +.. figure:: img/ui_gui_step_tutorial_assemble_final_gui_1.png The LifeBar and the EnergyBar align automatically Now, drag and drop the ``BombCounter.tscn`` and ``EmeraldCounter.tscn`` scenes onto the ``Counters`` node. They'll resize automatically. -.. figure:: ./img/ui_gui_step_tutorial_assemble_final_gui_2.png +.. figure:: img/ui_gui_step_tutorial_assemble_final_gui_2.png The nodes resize to take all the available vertical space @@ -570,7 +570,7 @@ in ``Counter.tscn``, we need to change the ``Size Flags`` on the the ``Vertical`` property, and check ``Shrink Center`` so the container centers inside the ``HBoxContainer``. -.. figure:: ./img/ui_gui_step_tutorial_assemble_final_gui_3.png +.. figure:: img/ui_gui_step_tutorial_assemble_final_gui_3.png Now both counters have a decent size @@ -588,7 +588,7 @@ value as on the LifeBar. The ``Count`` should now have some margin on the left. If you save and go back to the GUI scene, it will be aligned vertically with the ``LifeBar``. -.. figure:: ./img/ui_gui_step_tutorial_assemble_final_gui_4.png +.. figure:: img/ui_gui_step_tutorial_assemble_final_gui_4.png The 2 bars align perfectly @@ -616,7 +616,7 @@ the context of the game. Congratulations for getting to the end of this long tutorial. You can find the final project here: :download:`ui_gui_design.zip `. -.. figure:: ./img/ui_gui_design_final_result.png +.. figure:: img/ui_gui_design_final_result.png The final result diff --git a/getting_started/step_by_step/ui_introduction_to_the_ui_system.rst b/getting_started/step_by_step/ui_introduction_to_the_ui_system.rst index 7c7ffeca4..7dde87620 100644 --- a/getting_started/step_by_step/ui_introduction_to_the_ui_system.rst +++ b/getting_started/step_by_step/ui_introduction_to_the_ui_system.rst @@ -216,7 +216,7 @@ right and bottom edges. On the other hand, margins represent a distance to the anchor position in pixels, while anchors are relative to the parent container's size. -.. figure:: ./img/ui_anchor_and_margins.png +.. figure:: img/ui_anchor_and_margins.png Margins are relative to the anchor position, which is relative to the anchors. In practice, you'll often let the container update margins diff --git a/getting_started/step_by_step/your_first_game.rst b/getting_started/step_by_step/your_first_game.rst index b60639b46..21bbf864a 100644 --- a/getting_started/step_by_step/your_first_game.rst +++ b/getting_started/step_by_step/your_first_game.rst @@ -629,6 +629,7 @@ choose one of the three animation types: public override void _Ready() { + var _mobTypes = GetNode("AnimatedSprite").Frames.GetAnimationNames(); GetNode("AnimatedSprite").Animation = _mobTypes[_random.Next(0, _mobTypes.Length)]; } @@ -1094,6 +1095,7 @@ temporarily, such as "Get Ready". message.Text = "Dodge the\nCreeps!"; message.Show(); + await ToSignal(GetTree().CreateTimer(1), "timeout"); GetNode