From d4b40dfad40f0f280fcf244d1f4bad9e2c9e68c5 Mon Sep 17 00:00:00 2001 From: Relintai Date: Thu, 12 Jan 2023 19:29:11 +0100 Subject: [PATCH] Removed :ref:s. --- about/complying_with_licenses.rst | 4 +- about/docs_changelog.rst | 146 +++++++++--------- about/faq.rst | 38 ++--- about/introduction.rst | 24 +-- about/list_of_features.rst | 94 +++++------ about/troubleshooting.rst | 10 +- .../contributing/bisecting_regressions.rst | 4 +- .../class_reference_writing_guidelines.rst | 20 +-- .../contributing/code_style_guidelines.rst | 4 +- .../contributing_to_the_documentation.rst | 20 +-- .../contributing/cpp_usage_guidelines.rst | 8 +- .../contributing/docs_writing_guidelines.rst | 2 +- .../contributing/documentation_guidelines.rst | 14 +- .../editor_and_docs_localization.rst | 18 +-- community/contributing/pr_workflow.rst | 2 +- .../contributing/testing_pull_requests.rst | 4 +- .../updating_the_class_reference.rst | 14 +- community/contributing/ways_to_contribute.rst | 16 +- .../compiling/compiling_for_android.rst | 10 +- development/compiling/compiling_for_ios.rst | 8 +- development/compiling/compiling_for_osx.rst | 10 +- development/compiling/compiling_for_uwp.rst | 12 +- development/compiling/compiling_for_web.rst | 12 +- .../compiling/compiling_for_windows.rst | 12 +- development/compiling/compiling_for_x11.rst | 10 +- development/compiling/compiling_with_mono.rst | 8 +- development/compiling/getting_source.rst | 6 +- .../introduction_to_the_buildsystem.rst | 12 +- development/compiling/optimizing_for_size.rst | 4 +- .../cpp/binding_to_external_libraries.rst | 2 +- .../cpp/common_engine_methods_and_macros.rst | 2 +- .../cpp/configuring_an_ide/android_studio.rst | 2 +- development/cpp/configuring_an_ide/clion.rst | 2 +- .../cpp/configuring_an_ide/code_blocks.rst | 4 +- development/cpp/configuring_an_ide/index.rst | 2 +- .../cpp/configuring_an_ide/kdevelop.rst | 2 +- .../cpp/configuring_an_ide/qt_creator.rst | 6 +- .../cpp/configuring_an_ide/visual_studio.rst | 2 +- .../configuring_an_ide/visual_studio_code.rst | 6 +- development/cpp/configuring_an_ide/xcode.rst | 2 +- development/cpp/custom_audiostreams.rst | 2 +- development/cpp/custom_godot_servers.rst | 4 +- development/cpp/custom_modules_in_cpp.rst | 18 +-- .../cpp/custom_resource_format_loaders.rst | 6 +- development/cpp/object_class.rst | 12 +- development/cpp/using_cpp_profilers.rst | 2 +- development/editor/creating_icons.rst | 2 +- development/editor/editor_style_guide.rst | 4 +- .../introduction_to_editor_development.rst | 10 +- .../first_2d_game/02.player_scene.rst | 12 +- .../first_2d_game/03.coding_the_player.rst | 4 +- .../first_2d_game/04.creating_the_enemy.rst | 14 +- .../first_2d_game/05.the_main_game_scene.rst | 14 +- .../first_2d_game/06.heads_up_display.rst | 18 +-- .../first_2d_game/07.finishing-up.rst | 6 +- getting_started/first_2d_game/index.rst | 4 +- .../first_3d_game/02.player_input.rst | 2 +- .../first_3d_game/03.player_movement_code.rst | 2 +- .../first_3d_game/04.mob_scene.rst | 4 +- .../first_3d_game/06.jump_and_squash.rst | 10 +- .../first_3d_game/08.score_and_replay.rst | 8 +- .../first_3d_game/going_further.rst | 6 +- getting_started/first_3d_game/index.rst | 2 +- .../introduction/first_look_at_the_editor.rst | 6 +- .../introduction/godot_design_philosophy.rst | 2 +- .../introduction/introduction_to_godot.rst | 14 +- .../introduction/learning_new_features.rst | 4 +- getting_started/step_by_step/index.rst | 4 +- getting_started/step_by_step/instancing.rst | 6 +- .../step_by_step/nodes_and_scenes.rst | 4 +- .../step_by_step/scripting_first_script.rst | 14 +- .../step_by_step/scripting_languages.rst | 12 +- .../step_by_step/scripting_player_input.rst | 6 +- getting_started/step_by_step/signals.rst | 14 +- index.rst | 8 +- tutorials/2d/2d_lights_and_shadows.rst | 92 +++++------ tutorials/2d/2d_meshes.rst | 2 +- tutorials/2d/2d_movement.rst | 10 +- tutorials/2d/2d_sprite_animation.rst | 24 +-- tutorials/2d/2d_transforms.rst | 20 +-- tutorials/2d/canvas_layers.rst | 18 +-- tutorials/2d/custom_drawing_in_2d.rst | 18 +-- tutorials/2d/particle_systems_2d.rst | 6 +- tutorials/2d/using_tilemaps.rst | 14 +- tutorials/3d/3d_rendering_limitations.rst | 4 +- tutorials/3d/3d_text.rst | 2 +- tutorials/3d/baked_lightmaps.rst | 8 +- tutorials/3d/csg_tools.rst | 24 +-- tutorials/3d/gi_probes.rst | 6 +- tutorials/3d/high_dynamic_range.rst | 8 +- tutorials/3d/introduction_to_3d.rst | 30 ++-- tutorials/3d/lights_and_shadows.rst | 10 +- tutorials/3d/occluders.rst | 4 +- .../advanced_room_and_portal_usage.rst | 8 +- .../3d/portals/editing_rooms_and_portals.rst | 14 +- .../first_steps_with_rooms_and_portals.rst | 14 +- .../introduction_to_rooms_and_portals.rst | 2 +- .../3d/portals/rooms_and_portals_example.rst | 12 +- .../using_objects_in_rooms_and_portals.rst | 6 +- .../3d/procedural_geometry/arraymesh.rst | 32 ++-- .../procedural_geometry/immediategeometry.rst | 4 +- tutorials/3d/procedural_geometry/index.rst | 22 +-- .../3d/procedural_geometry/meshdatatool.rst | 8 +- .../3d/procedural_geometry/surfacetool.rst | 8 +- tutorials/3d/reflection_probes.rst | 2 +- tutorials/3d/spatial_material.rst | 2 +- tutorials/3d/using_gridmaps.rst | 22 +-- tutorials/3d/using_multi_mesh_instance.rst | 6 +- tutorials/3d/using_transforms.rst | 12 +- tutorials/animation/2d_skeletons.rst | 2 +- tutorials/animation/animation_tree.rst | 10 +- tutorials/animation/cutout_animation.rst | 12 +- tutorials/animation/introduction.rst | 16 +- tutorials/animation/playing_videos.rst | 20 +-- tutorials/assets_pipeline/import_process.rst | 8 +- .../importing_audio_samples.rst | 2 +- .../assets_pipeline/importing_images.rst | 2 +- .../assets_pipeline/importing_scenes.rst | 30 ++-- .../importing_translations.rst | 4 +- tutorials/audio/audio_buses.rst | 8 +- tutorials/audio/audio_streams.rst | 4 +- tutorials/audio/recording_with_microphone.rst | 8 +- tutorials/audio/sync_with_audio.rst | 10 +- .../autoloads_versus_internal_nodes.rst | 10 +- tutorials/best_practices/data_preferences.rst | 32 ++-- tutorials/best_practices/godot_interfaces.rst | 24 +-- .../best_practices/godot_notifications.rst | 20 +-- .../introduction_best_practices.rst | 2 +- .../best_practices/logic_preferences.rst | 10 +- .../best_practices/node_alternatives.rst | 20 +-- .../best_practices/scene_organization.rst | 28 ++-- .../best_practices/scenes_versus_scripts.rst | 8 +- .../best_practices/what_are_godot_classes.rst | 10 +- tutorials/editor/command_line_tutorial.rst | 26 ++-- tutorials/editor/index.rst | 2 +- tutorials/editor/managing_editor_features.rst | 4 +- tutorials/editor/using_the_web_editor.rst | 2 +- tutorials/export/android_custom_build.rst | 4 +- .../changing_application_icon_for_windows.rst | 2 +- tutorials/export/exporting_basics.rst | 4 +- tutorials/export/exporting_for_android.rst | 6 +- .../exporting_for_dedicated_servers.rst | 6 +- tutorials/export/exporting_for_ios.rst | 6 +- tutorials/export/exporting_for_linux.rst | 2 +- tutorials/export/exporting_for_macos.rst | 8 +- tutorials/export/exporting_for_uwp.rst | 2 +- tutorials/export/exporting_for_web.rst | 48 +++--- tutorials/export/exporting_for_windows.rst | 2 +- tutorials/export/exporting_pcks.rst | 6 +- tutorials/export/exporting_projects.rst | 6 +- tutorials/export/feature_tags.rst | 8 +- tutorials/export/one-click_deploy.rst | 2 +- tutorials/export/running_on_macos.rst | 2 +- tutorials/i18n/internationalizing_games.rst | 20 +-- tutorials/i18n/localization_using_gettext.rst | 6 +- .../inputs/controllers_gamepads_joysticks.rst | 10 +- tutorials/inputs/custom_mouse_cursor.rst | 4 +- tutorials/inputs/handling_quit_requests.rst | 6 +- tutorials/inputs/input_examples.rst | 44 +++--- tutorials/inputs/inputevent.rst | 70 ++++----- .../inputs/mouse_and_input_coordinates.rst | 2 +- tutorials/io/background_loading.rst | 2 +- tutorials/io/binary_serialization_api.rst | 56 +++---- tutorials/io/data_paths.rst | 20 +-- tutorials/io/saving_games.rst | 14 +- tutorials/math/beziers_and_curves.rst | 12 +- tutorials/math/interpolation.rst | 10 +- tutorials/math/matrices_and_transforms.rst | 34 ++-- tutorials/math/random_number_generation.rst | 28 ++-- tutorials/math/vector_math.rst | 12 +- tutorials/math/vectors_advanced.rst | 6 +- .../navigation/real_time_navigation_3d.rst | 20 +-- .../networking/high_level_multiplayer.rst | 32 ++-- tutorials/networking/http_client_class.rst | 8 +- tutorials/networking/http_request_class.rst | 10 +- tutorials/networking/ssl_certificates.rst | 4 +- tutorials/networking/webrtc.rst | 8 +- tutorials/networking/websocket.rst | 4 +- tutorials/performance/batching.rst | 46 +++--- tutorials/performance/cpu_optimization.rst | 22 +-- .../performance/general_optimization.rst | 2 +- tutorials/performance/gpu_optimization.rst | 8 +- tutorials/performance/index.rst | 2 +- .../performance/optimizing_3d_performance.rst | 14 +- .../performance/threads/thread_safe_apis.rst | 2 +- .../threads/using_multiple_threads.rst | 18 +-- tutorials/performance/using_multimesh.rst | 12 +- tutorials/performance/using_servers.rst | 44 +++--- .../animating_thousands_of_fish.rst | 20 +-- .../controlling_thousands_of_fish.rst | 16 +- tutorials/physics/collision_shapes_3d.rst | 20 +-- .../advanced_physics_interpolation.rst | 22 +-- .../physics_interpolation_introduction.rst | 4 +- ...hysics_interpolation_quick_start_guide.rst | 6 +- .../using_physics_interpolation.rst | 10 +- tutorials/physics/kinematic_character_2d.rst | 4 +- tutorials/physics/physics_introduction.rst | 58 +++---- tutorials/physics/ragdoll_system.rst | 4 +- tutorials/physics/ray-casting.rst | 26 ++-- tutorials/physics/rigid_body.rst | 6 +- tutorials/physics/soft_body.rst | 4 +- tutorials/physics/using_area_2d.rst | 12 +- tutorials/physics/using_kinematic_body_2d.rst | 18 +-- .../android/android_in_app_purchases.rst | 4 +- tutorials/platform/android/android_plugin.rst | 2 +- .../platform/customizing_html5_shell.rst | 4 +- tutorials/platform/html5_shell_classref.rst | 6 +- tutorials/platform/ios/ios_plugin.rst | 2 +- .../platform/mobile_rendering_limitations.rst | 6 +- tutorials/plugins/editor/import_plugins.rst | 42 ++--- .../plugins/editor/inspector_plugins.rst | 24 +-- .../editor/making_main_screen_plugins.rst | 4 +- tutorials/plugins/editor/making_plugins.rst | 26 ++-- tutorials/plugins/editor/spatial_gizmos.rst | 22 +-- .../plugins/editor/visual_shader_plugins.rst | 8 +- .../plugins/running_code_in_the_editor.rst | 8 +- tutorials/rendering/multiple_resolutions.rst | 18 +-- tutorials/rendering/viewports.rst | 132 ++++++++-------- .../scripting/change_scenes_manually.rst | 18 +-- .../scripting/creating_script_templates.rst | 6 +- .../scripting/cross_language_scripting.rst | 18 +-- tutorials/scripting/debug/debugger_panel.rst | 2 +- .../debug/overview_of_debugging_tools.rst | 4 +- .../scripting/evaluating_expressions.rst | 8 +- tutorials/scripting/filesystem.rst | 2 +- .../scripting/gdscript/gdscript_advanced.rst | 4 +- .../scripting/gdscript/gdscript_basics.rst | 102 ++++++------ .../scripting/gdscript/gdscript_exports.rst | 22 +-- .../gdscript/gdscript_styleguide.rst | 8 +- tutorials/scripting/gdscript/index.rst | 2 +- .../scripting/gdscript/static_typing.rst | 6 +- .../scripting/gdscript/warning_system.rst | 2 +- tutorials/scripting/groups.rst | 8 +- .../scripting/idle_and_physics_processing.rst | 6 +- tutorials/scripting/index.rst | 2 +- .../scripting/instancing_with_signals.rst | 2 +- .../scripting/nodes_and_scene_instances.rst | 6 +- tutorials/scripting/overridable_functions.rst | 20 +-- tutorials/scripting/pausing_games.rst | 4 +- tutorials/scripting/resources.rst | 34 ++-- tutorials/scripting/scene_tree.rst | 28 ++-- tutorials/scripting/singletons_autoload.rst | 14 +- tutorials/shaders/advanced_postprocessing.rst | 14 +- .../converting_glsl_to_godot_shaders.rst | 10 +- tutorials/shaders/custom_postprocessing.rst | 18 +-- tutorials/shaders/introduction_to_shaders.rst | 14 +- tutorials/shaders/screen-reading_shaders.rst | 8 +- tutorials/shaders/shader_materials.rst | 6 +- .../shader_reference/canvas_item_shader.rst | 4 +- .../shader_reference/shading_language.rst | 10 +- .../shader_reference/spatial_shader.rst | 4 +- .../shaders/using_viewport_as_texture.rst | 52 +++---- tutorials/shaders/your_first_shader/index.rst | 2 +- .../your_first_2d_shader.rst | 22 +-- .../your_first_3d_shader.rst | 42 ++--- .../your_second_3d_shader.rst | 14 +- tutorials/ui/bbcode_in_richtextlabel.rst | 22 +-- tutorials/ui/custom_gui_controls.rst | 18 +-- tutorials/ui/gui_containers.rst | 24 +-- tutorials/ui/gui_navigation.rst | 8 +- tutorials/ui/gui_skinning.rst | 38 ++--- tutorials/ui/gui_theme_type_variations.rst | 10 +- tutorials/ui/gui_using_theme_editor.rst | 6 +- 263 files changed, 1792 insertions(+), 1792 deletions(-) diff --git a/about/complying_with_licenses.rst b/about/complying_with_licenses.rst index 885bb46..f75df0e 100644 --- a/about/complying_with_licenses.rst +++ b/about/complying_with_licenses.rst @@ -71,7 +71,7 @@ Some games have a special menu (often in the settings) to display licenses. Output log ^^^^^^^^^^ -Just printing the licensing text using the :ref:`print() ` +Just printing the licensing text using the `print() ` function may be enough on platforms where a global output log is readable. This is the case on desktop platforms, Android and HTML5 (but not iOS and UWP). @@ -163,5 +163,5 @@ as the latest version of OpenSSL currently uses (as of April 2022). .. note:: If you exported your project using a - :ref:`custom build with specific modules disabled `, + `custom build with specific modules disabled `, you don't need to list the disabled modules' licenses in your exported project. diff --git a/about/docs_changelog.rst b/about/docs_changelog.rst index 5f9ea44..34d19a8 100644 --- a/about/docs_changelog.rst +++ b/about/docs_changelog.rst @@ -5,7 +5,7 @@ Documentation changelog The documentation is continually being improved. The release of version 3.2 includes many new tutorials, many fixes and updates for old tutorials, and many updates -to the :ref:`class reference `. Below is a list of new tutorials +to the `class reference `. Below is a list of new tutorials added since version 3.1. .. note:: This document only contains new tutorials so not all changes are reflected, @@ -17,88 +17,88 @@ New tutorials since version 3.1 Project workflow ^^^^^^^^^^^^^^^^ -- :ref:`doc_android_custom_build` +- `doc_android_custom_build` 2D ^^ -- :ref:`doc_2d_sprite_animation` +- `doc_2d_sprite_animation` Audio ^^^^^ -- :ref:`doc_recording_with_microphone` -- :ref:`doc_sync_with_audio` +- `doc_recording_with_microphone` +- `doc_sync_with_audio` Math ^^^^ -- :ref:`doc_beziers_and_curves` -- :ref:`doc_interpolation` +- `doc_beziers_and_curves` +- `doc_interpolation` Inputs ^^^^^^ -- :ref:`doc_input_examples` +- `doc_input_examples` Internationalization ^^^^^^^^^^^^^^^^^^^^ -- :ref:`doc_localization_using_gettext` +- `doc_localization_using_gettext` Shading ^^^^^^^ - Your First Shader Series: - - :ref:`doc_introduction_to_shaders` - - :ref:`doc_your_first_canvasitem_shader` - - :ref:`doc_your_first_spatial_shader` - - :ref:`doc_your_second_spatial_shader` -- :ref:`doc_visual_shaders` + - `doc_introduction_to_shaders` + - `doc_your_first_canvasitem_shader` + - `doc_your_first_spatial_shader` + - `doc_your_second_spatial_shader` +- `doc_visual_shaders` Networking ^^^^^^^^^^ -- :ref:`doc_webrtc` +- `doc_webrtc` VR ^^ -- :ref:`doc_vr_starter_tutorial_part_one` -- :ref:`doc_vr_starter_tutorial_part_two` +- `doc_vr_starter_tutorial_part_one` +- `doc_vr_starter_tutorial_part_two` Plugins ^^^^^^^ -- :ref:`doc_android_plugin` -- :ref:`doc_inspector_plugins` -- :ref:`doc_visual_shader_plugins` +- `doc_android_plugin` +- `doc_inspector_plugins` +- `doc_visual_shader_plugins` Multi-threading ^^^^^^^^^^^^^^^ -- :ref:`doc_using_multiple_threads` +- `doc_using_multiple_threads` Creating content ^^^^^^^^^^^^^^^^ Procedural geometry series: - - :ref:`Procedural geometry ` - - :ref:`doc_arraymesh` - - :ref:`doc_surfacetool` - - :ref:`doc_meshdatatool` - - :ref:`doc_immediategeometry` + - `Procedural geometry ` + - `doc_arraymesh` + - `doc_surfacetool` + - `doc_meshdatatool` + - `doc_immediategeometry` Optimization ^^^^^^^^^^^^ -- :ref:`doc_using_multimesh` -- :ref:`doc_using_servers` +- `doc_using_multimesh` +- `doc_using_servers` Legal ^^^^^ -- :ref:`doc_complying_with_licenses` +- `doc_complying_with_licenses` New tutorials since version 3.0 ------------------------------- @@ -106,116 +106,116 @@ New tutorials since version 3.0 Step by step ^^^^^^^^^^^^ -- :ref:`doc_signals` -- :ref:`doc_exporting_basics` +- `doc_signals` +- `doc_exporting_basics` Scripting ^^^^^^^^^ -- :ref:`doc_gdscript_static_typing` +- `doc_gdscript_static_typing` Project workflow ^^^^^^^^^^^^^^^^ Best Practices: -- :ref:`doc_introduction_best_practices` -- :ref:`doc_what_are_godot_classes` -- :ref:`doc_scene_organization` -- :ref:`doc_scenes_versus_scripts` -- :ref:`doc_autoloads_versus_internal_nodes` -- :ref:`doc_node_alternatives` -- :ref:`doc_godot_interfaces` -- :ref:`doc_godot_notifications` -- :ref:`doc_data_preferences` -- :ref:`doc_logic_preferences` +- `doc_introduction_best_practices` +- `doc_what_are_godot_classes` +- `doc_scene_organization` +- `doc_scenes_versus_scripts` +- `doc_autoloads_versus_internal_nodes` +- `doc_node_alternatives` +- `doc_godot_interfaces` +- `doc_godot_notifications` +- `doc_data_preferences` +- `doc_logic_preferences` 2D ^^ -- :ref:`doc_2d_lights_and_shadows` -- :ref:`doc_2d_meshes` +- `doc_2d_lights_and_shadows` +- `doc_2d_meshes` 3D ^^ -- :ref:`doc_csg_tools` -- :ref:`doc_animating_thousands_of_fish` -- :ref:`doc_controlling_thousands_of_fish` +- `doc_csg_tools` +- `doc_animating_thousands_of_fish` +- `doc_controlling_thousands_of_fish` Physics ^^^^^^^ -- :ref:`doc_ragdoll_system` -- :ref:`doc_soft_body` +- `doc_ragdoll_system` +- `doc_soft_body` Animation ^^^^^^^^^ -- :ref:`doc_2d_skeletons` -- :ref:`doc_animation_tree` +- `doc_2d_skeletons` +- `doc_animation_tree` GUI ^^^ -- :ref:`doc_gui_containers` +- `doc_gui_containers` Viewports ^^^^^^^^^ -- :ref:`doc_viewport_as_texture` -- :ref:`doc_custom_postprocessing` +- `doc_viewport_as_texture` +- `doc_custom_postprocessing` Shading ^^^^^^^ -- :ref:`doc_converting_glsl_to_godot_shaders` -- :ref:`doc_advanced_postprocessing` +- `doc_converting_glsl_to_godot_shaders` +- `doc_advanced_postprocessing` Shading Reference: -- :ref:`doc_introduction_to_shaders` -- :ref:`doc_shading_language` -- :ref:`doc_spatial_shader` -- :ref:`doc_canvas_item_shader` -- :ref:`doc_particle_shader` +- `doc_introduction_to_shaders` +- `doc_shading_language` +- `doc_spatial_shader` +- `doc_canvas_item_shader` +- `doc_particle_shader` Plugins ^^^^^^^ -- :ref:`doc_making_main_screen_plugins` -- :ref:`doc_spatial_gizmo_plugins` +- `doc_making_main_screen_plugins` +- `doc_spatial_gizmo_plugins` Platform-specific ^^^^^^^^^^^^^^^^^ -- :ref:`doc_customizing_html5_shell` +- `doc_customizing_html5_shell` Multi-threading ^^^^^^^^^^^^^^^ -- :ref:`doc_thread_safe_apis` +- `doc_thread_safe_apis` Creating content ^^^^^^^^^^^^^^^^ -- :ref:`doc_making_trees` +- `doc_making_trees` Miscellaneous ^^^^^^^^^^^^^ -- :ref:`doc_jitter_stutter` -- :ref:`doc_running_code_in_the_editor` -- :ref:`doc_change_scenes_manually` -- :ref:`doc_gles2_gles3_differences` +- `doc_jitter_stutter` +- `doc_running_code_in_the_editor` +- `doc_change_scenes_manually` +- `doc_gles2_gles3_differences` Compiling ^^^^^^^^^ -- :ref:`doc_optimizing_for_size` -- :ref:`doc_compiling_with_script_encryption_key` +- `doc_optimizing_for_size` +- `doc_compiling_with_script_encryption_key` Engine development ^^^^^^^^^^^^^^^^^^ -- :ref:`doc_binding_to_external_libraries` +- `doc_binding_to_external_libraries` diff --git a/about/faq.rst b/about/faq.rst index 74c5d5d..e5c13a9 100644 --- a/about/faq.rst +++ b/about/faq.rst @@ -38,7 +38,7 @@ Which platforms are supported by Godot? * Windows * macOS * X11 (Linux, \*BSD) -* :ref:`Web ` +* `Web ` * Android (experimental) **For exporting your games:** @@ -60,15 +60,15 @@ Additionally, there is some unofficial third-party work being done on building for some consoles. However, none of this is included in the default build scripts or export templates at this time. -For more on this, see the sections on :ref:`exporting ` -and :ref:`compiling Godot yourself `. +For more on this, see the sections on `exporting ` +and `compiling Godot yourself `. Which programming languages are supported in Godot? --------------------------------------------------- The officially supported languages for Godot are GDScript, Visual Scripting, C#, and C++. See the subcategories for each language in the -:ref:`scripting ` section. +`scripting ` section. If you are just starting out with either Godot or game development in general, GDScript is the recommended language to learn and use since it is native to Godot. @@ -99,7 +99,7 @@ up to maximize Godot's potential in the least amount of code, affording both nov and expert developers alike to capitalize on Godot's strengths as fast as possible. If you've ever written anything in a language like Python before then you'll feel right at home. For examples, history, and a complete overview of the power GDScript -offers you, check out the :ref:`GDScript scripting guide `. +offers you, check out the `GDScript scripting guide `. There are several reasons to use GDScript--especially when you are prototyping, in alpha/beta stages of your project, or are not creating the next AAA title--but the @@ -123,7 +123,7 @@ once you see how powerful it is and rapid your development becomes, we think GDS will grow on you. More information about getting comfortable with GDScript or dynamically typed -languages can be found in the :ref:`doc_gdscript_more_efficiently` tutorial. +languages can be found in the `doc_gdscript_more_efficiently` tutorial. What were the motivations behind creating GDScript? --------------------------------------------------- @@ -225,7 +225,7 @@ Linux This is typically ``/usr/local/bin/godot`` or ``/usr/bin/godot``. Doing this requires administrator privileges, but this also allows you to - :ref:`run the Godot editor from a terminal ` by entering ``godot``. + `run the Godot editor from a terminal ` by entering ``godot``. - If you cannot move the Godot editor binary to a protected location, you can keep the binary somewhere in your home directory, and modify the ``Path=`` @@ -247,10 +247,10 @@ administrator privileges. However, configuration files will be written to the user-wide configuration or data directory. This is usually a good approach, but this means configuration files will not carry across machines if you copy the folder containing the Godot executable. -See :ref:`doc_data_paths` for more information. +See `doc_data_paths` for more information. If *true* portable operation is desired (e.g. for use on an USB stick), -follow the steps in :ref:`doc_data_paths_self_contained_mode`. +follow the steps in `doc_data_paths_self_contained_mode`. Why does Godot use Vulkan or OpenGL instead of Direct3D? -------------------------------------------------------- @@ -309,7 +309,7 @@ functionality in Godot. This is why we are aiming to move some core functionality to officially supported add-ons in future versions of Godot. In terms of binary size, this also has the advantage of making you pay only for what you actually use in your project. (In the meantime, you can -:ref:`compile custom export templates with unused features disabled ` +`compile custom export templates with unused features disabled ` to optimize the distribution size of your project.) How should assets be created to handle multiple resolutions and aspect ratios? @@ -336,15 +336,15 @@ This is mostly needed for 2D, as in 3D it's just a matter of Camera XFov or YFov and the longer the time it will take for loading. 2. Use the stretch options in Godot; 2D stretching while keeping aspect - ratios works best. Check the :ref:`doc_multiple_resolutions` tutorial + ratios works best. Check the `doc_multiple_resolutions` tutorial on how to achieve this. 3. Determine a minimum resolution and then decide if you want your game to stretch vertically or horizontally for different aspect ratios, or if there is one aspect ratio and you want black bars to appear - instead. This is also explained in :ref:`doc_multiple_resolutions`. + instead. This is also explained in `doc_multiple_resolutions`. -4. For user interfaces, use the :ref:`anchoring ` +4. For user interfaces, use the `anchoring ` to determine where controls should stay and move. If UIs are more complex, consider learning about Containers. @@ -359,7 +359,7 @@ How can I extend Godot? ----------------------- For extending Godot, like creating Godot Editor plugins or adding support -for additional languages, take a look at :ref:`EditorPlugins ` +for additional languages, take a look at `EditorPlugins ` and tool scripts. Also, see the official blog posts on these topics: @@ -375,7 +375,7 @@ integrates with Godot. When is the next release of Godot out? -------------------------------------- -When it's ready! See :ref:`doc_release_policy_when_is_next_release_out` for more +When it's ready! See `doc_release_policy_when_is_next_release_out` for more information. I would like to contribute! How can I get started? @@ -433,7 +433,7 @@ Yes! Godot features an extensive built-in UI system, and its small distribution size can make it a suitable alternative to frameworks like Electron or Qt. When creating a non-game application, make sure to enable -:ref:`low-processor mode ` +`low-processor mode ` in the Project Settings to decrease CPU and GPU usage. That said, we wouldn't recommend using Godot to create a *mobile* application @@ -474,9 +474,9 @@ have to deal with the LGPL licensing caveats that come with GTK or Qt. Lastly, this means Godot is "eating its own dog food" since the editor itself is one of the most complex users of Godot's UI system. -This custom UI toolkit :ref:`can't be used as a library `, +This custom UI toolkit `can't be used as a library `, but you can still -:ref:`use Godot to create non-game applications by using the editor `. +`use Godot to create non-game applications by using the editor `. .. _doc_faq_why_not_stl: @@ -535,7 +535,7 @@ performance parts and GDScript (or C#) for the rest of the game. How can I support Godot development or contribute? -------------------------------------------------- -See :ref:`doc_ways_to_contribute`. +See `doc_ways_to_contribute`. Who is working on Godot? How can I contact you? ----------------------------------------------- diff --git a/about/introduction.rst b/about/introduction.rst index 20509d4..b0b547e 100644 --- a/about/introduction.rst +++ b/about/introduction.rst @@ -20,12 +20,12 @@ where to look if you need info on a specific feature. Before you start ---------------- -The :ref:`Tutorials and resources ` page lists +The `Tutorials and resources ` page lists video tutorials contributed by the community. If you prefer video to text, those may be worth a look. In case you have trouble with one of the tutorials or your project, -you can find help on the various :ref:`Community channels `, +you can find help on the various `Community channels `, especially the Godot Discord community, Q&A, and IRC. About Godot Engine @@ -50,7 +50,7 @@ if you need a quick writeup about Godot Engine. Freedom Conservancy `_ not-for-profit. For a more in-depth view of the engine, you are encouraged to read this -documentation further, especially the :ref:`Step by step +documentation further, especially the `Step by step ` tutorial. About the documentation @@ -80,29 +80,29 @@ This documentation is organized in five sections with an impressively unbalanced distribution of contents – but the way it is split up should be relatively intuitive: -- The :ref:`sec-general` section contains this introduction as well as +- The `sec-general` section contains this introduction as well as information about the engine, its history, its licensing, authors, etc. It - also contains the :ref:`doc_faq`. -- The :ref:`sec-learn` section is the *raison d'être* of this + also contains the `doc_faq`. +- The `sec-learn` section is the *raison d'être* of this documentation, as it contains all the necessary information on using the - engine to make games. It starts with the :ref:`Step by step + engine to make games. It starts with the `Step by step ` tutorial which should be the entry point for all new users. -- The :ref:`sec-tutorials` section can be read as needed, +- The `sec-tutorials` section can be read as needed, in any order. It contains feature-specific tutorials and documentation. -- The :ref:`sec-devel` section is intended for advanced users and contributors +- The `sec-devel` section is intended for advanced users and contributors to the engine development, with information on compiling the engine, developing C++ modules or editor plugins. -- The :ref:`sec-community` section gives information related to contributing to +- The `sec-community` section gives information related to contributing to engine development and the life of its community, e.g. how to report bugs, help with the documentation, etc. It also points to various community channels like IRC and Discord and contains a list of recommended third-party tutorials outside of this documentation. -- Finally, the :ref:`sec-class-ref` is the documentation of the Godot API, +- Finally, the `sec-class-ref` is the documentation of the Godot API, which is also available directly within the engine's script editor. It is generated automatically from a file in the main source repository, therefore the generated files of the documentation are not meant to be modified. See - :ref:`doc_updating_the_class_reference` for details. + `doc_updating_the_class_reference` for details. In addition to this documentation you may also want to take a look at the various `Godot demo projects `_. diff --git a/about/list_of_features.rst b/about/list_of_features.rst index 9394b5b..20984a5 100644 --- a/about/list_of_features.rst +++ b/about/list_of_features.rst @@ -33,8 +33,8 @@ Platforms - Android 4.4 and later. - iOS 10.0 and later. -- :ref:`Consoles `. -- :ref:`Headless Linux and macOS servers `. +- `Consoles `. +- `Headless Linux and macOS servers `. Godot aims to be as platform-independent as possible and can be ported to new platforms with relative ease. @@ -46,9 +46,9 @@ Editor - Scene tree editor. - Built-in script editor. -- Support for :ref:`external script editors ` such as +- Support for `external script editors ` such as Visual Studio Code or Vim. -- GDScript :ref:`debugger `. +- GDScript `debugger `. - No support for debugging in threads yet. - Performance monitoring tools. @@ -71,10 +71,10 @@ Editor **Plugins:** - Editor plugins can be downloaded from the - :ref:`asset library ` to extend editor functionality. -- :ref:`Create your own plugins ` using GDScript to add new + `asset library ` to extend editor functionality. +- `Create your own plugins ` using GDScript to add new features or speed up your workflow. -- :ref:`Download projects from the asset library ` +- `Download projects from the asset library ` in the project manager and import them directly. 2D graphics @@ -275,7 +275,7 @@ Editor **Performance:** -- Occlusion culling with :ref:`rooms and portals `. +- Occlusion culling with `rooms and portals `. Supports gameplay notifications with primary and secondary visibility to disable AI/physics processing for nodes that don't need it. - Real-time occluder shapes (sphere and polygon). Not as effective as rooms and portals @@ -291,8 +291,8 @@ Editor ^^^^^^^^ - Built-in meshes: cube, cylinder/cone, (hemi)sphere, prism, plane, quad. -- Tools for :ref:`procedural geometry generation `. -- :ref:`Constructive solid geometry ` (intended for prototyping). +- Tools for `procedural geometry generation `. +- `Constructive solid geometry ` (intended for prototyping). - Path3D node to represent a path in 3D space. - Can be drawn in the editor or generated procedurally. @@ -326,7 +326,7 @@ Shaders - *2D:* Custom vertex, fragment, and light shaders. - *3D:* Custom vertex, fragment, light, and sky shaders. -- Text-based shaders using a :ref:`shader language inspired by GLSL `. +- Text-based shaders using a `shader language inspired by GLSL `. - Visual shader editor. - Support for visual shader plugins. @@ -338,19 +338,19 @@ Scripting - Object-oriented design pattern with scripts extending nodes. - Signals and groups for communicating between scripts. -- Support for :ref:`cross-language scripting `. +- Support for `cross-language scripting `. - Many 2D and 3D linear algebra data types such as vectors and transforms. -:ref:`GDScript: ` +`GDScript: ` -- :ref:`High-level interpreted language ` with - :ref:`optional static typing `. +- `High-level interpreted language ` with + `optional static typing `. - Syntax inspired by Python. - Syntax highlighting is provided on GitHub. -- :ref:`Use threads ` to perform asynchronous actions +- `Use threads ` to perform asynchronous actions or make use of multiple processor cores. -:ref:`C#: ` +`C#: ` - Packaged in a separate binary to keep file sizes and dependencies down. - Uses Mono 6.x. @@ -360,9 +360,9 @@ Scripting - Supports all platforms. - Using an external editor is recommended to benefit from IDE functionality. -:ref:`VisualScript: ` +`VisualScript: ` -- :ref:`Graph-based visual scripting language `. +- `Graph-based visual scripting language `. - Works best when used for specific purposes (such as level-specific logic) rather than as a language to create entire projects. @@ -386,7 +386,7 @@ Scripting Future Godot 4.x releases may have VisualScript reimplemented as an extension. While Godot 3.x will keep VisualScript supported, we recommend - :ref:`trying out GDScript ` instead, + `trying out GDScript ` instead, especially if you intend to migrate your project to Godot 4. Audio @@ -399,7 +399,7 @@ Audio - Optional Doppler effect in 2D and 3D. -- Support for re-routable :ref:`audio buses ` and effects +- Support for re-routable `audio buses ` and effects with dozens of effects included. - Listener2D and Listener3D nodes to listen from a position different than the camera. - Audio input to record microphones with real-time access using the AudioEffectCapture class. @@ -416,11 +416,11 @@ Audio Import ^^^^^^ -- Support for :ref:`custom import plugins `. +- Support for `custom import plugins `. **Formats:** -- *Images:* See :ref:`doc_import_images`. +- *Images:* See `doc_import_images`. - *Audio:* - WAV with optional IMA-ADPCM compression. @@ -492,8 +492,8 @@ Internationalization ^^^^^^^^^^^^^^^^^^^^ - Full support for Unicode including emoji. -- Store localization strings using :ref:`CSV ` - or :ref:`gettext `. +- Store localization strings using `CSV ` + or `gettext `. - Use localized strings in your project automatically in GUI elements or by using the ``tr()`` function. - Support for right-to-left typesetting and text shaping planned in Godot 4.0. @@ -516,10 +516,10 @@ Windowing and OS integration - Execute commands in a blocking or non-blocking manner. - Open file paths and URLs using default or custom protocol handlers (if registered on the system). - Parse custom command line arguments. -- :ref:`Headless/server binaries ` can be - downloaded for Linux and :ref:`compiled for macOS `. +- `Headless/server binaries ` can be + downloaded for Linux and `compiled for macOS `. Any binary can be used without a window using the ``--no-window`` - :ref:`command line argument `. + `command line argument `. Mobile ^^^^^^ @@ -552,7 +552,7 @@ The editor UI can easily be extended in many ways using add-ons. - Dropdown menus using PopupMenu and OptionButton. - Scrollbars. - Labels. -- RichTextLabel for :ref:`text formatted using BBCode `. +- RichTextLabel for `text formatted using BBCode `. - Trees (can also be used to represent tables). - Color picker with RGB and HSV modes. - Containers (horizontal, vertical, grid, flow, center, margin, aspect ratio, draggable splitter, ...). @@ -563,11 +563,11 @@ The editor UI can easily be extended in many ways using add-ons. - Anchors to keep GUI elements in a specific corner, edge or centered. - Containers to place GUI elements automatically following certain rules. - - :ref:`Stack ` layouts. - - :ref:`Grid ` layouts. - - :ref:`Margin ` and :ref:`centered ` + - `Stack ` layouts. + - `Grid ` layouts. + - `Margin ` and `centered ` layouts. - - :ref:`Draggable splitter ` 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. @@ -578,11 +578,11 @@ The editor UI can easily be extended in many ways using add-ons. - Generate a theme based on the current editor theme settings. -- Procedural vector-based theming using :ref:`class_StyleBoxFlat`. +- Procedural vector-based theming using `class_StyleBoxFlat`. - Supports rounded/beveled corners, drop shadows, per-border widths and antialiasing. -- Texture-based theming using :ref:`class_StyleBoxTexture`. +- Texture-based theming using `class_StyleBoxTexture`. Godot's small distribution size can make it a suitable alternative to frameworks like Electron or Qt. @@ -591,7 +591,7 @@ Animation ^^^^^^^^^ - Direct kinematics and inverse kinematics. -- :ref:`Tween ` node to easily perform procedural animations by code. +- `Tween ` node to easily perform procedural animations by code. - Support for animating any property with customizable interpolation. - Support for calling methods in animation tracks. - Support for playing sounds in animation tracks. @@ -600,42 +600,42 @@ Animation File formats ^^^^^^^^^^^^ -- Scenes and resources can be saved in :ref:`text-based ` or binary formats. +- Scenes and resources can be saved in `text-based ` or binary formats. - Text-based formats are human-readable and more friendly to version control. - Binary formats are faster to save/load for large scenes/resources. -- Read and write text or binary files using :ref:`class_File`. +- Read and write text or binary files using `class_File`. - Can optionally be compressed or encrypted. -- Read and write :ref:`class_JSON` files. -- Read and write INI-style configuration files using :ref:`class_ConfigFile`. +- Read and write `class_JSON` files. +- Read and write INI-style configuration files using `class_ConfigFile`. - Can (de)serialize any Godot datatype, including Vector2/3, Color, ... -- Read XML files using :ref:`class_XMLParser`. +- Read XML files using `class_XMLParser`. - Pack game data into a PCK file (custom format optimized for fast seeking), into a ZIP archive, or directly into the executable for single-file distribution. -- :ref:`Export additional PCK files` that can be read +- `Export additional PCK files` that can be read by the engine to support mods and DLCs. Miscellaneous ^^^^^^^^^^^^^ -- :ref:`Low-level access to servers ` which allows bypassing +- `Low-level access to servers ` which allows bypassing the scene tree's overhead when needed. -- :ref:`Command line interface ` for automation. +- `Command line interface ` for automation. - Export and deploy projects using continuous integration platforms. - `Shell completion scripts `__ are available for Bash, zsh and fish. -- Support for :ref:`C++ modules ` statically linked +- Support for `C++ modules ` statically linked into the engine binary. - Engine and editor written in C++03. - - Can be :ref:`compiled ` using GCC, + - Can be `compiled ` using GCC, Clang and MSVC. MinGW is also supported. - Friendly towards packagers. In most cases, system libraries can be used instead of the ones provided by Godot. The build system doesn't download anything. @@ -644,7 +644,7 @@ Miscellaneous - Licensed under the permissive MIT license. - - Open developement process with :ref:`contributions welcome `. + - Open developement process with `contributions welcome `. .. seealso:: diff --git a/about/troubleshooting.rst b/about/troubleshooting.rst index 9ac306b..3e456e9 100644 --- a/about/troubleshooting.rst +++ b/about/troubleshooting.rst @@ -7,7 +7,7 @@ This page lists common issues encountered when using Godot and possible solution .. seealso:: - See :ref:`doc_using_the_web_editor` for caveats specific to the HTML5 version + See `doc_using_the_web_editor` for caveats specific to the HTML5 version of the Godot editor. Everything I do in the editor or project manager appears delayed by one frame. @@ -81,7 +81,7 @@ done to improve performance, especially on integrated graphics, where rendering To resolve this, open **Project > Project Settings** and enable **Display > Window > Dpi > Allow Hidpi**. On top of that, make sure your project is -configured to support :ref:`multiple resolutions `. +configured to support `multiple resolutions `. The project window doesn't appear centered when I run the project. ------------------------------------------------------------------ @@ -89,7 +89,7 @@ The project window doesn't appear centered when I run the project. This is a `known bug `__. To resolve this, open **Project > Project Settings** and enable **Display > Window > Dpi > Allow Hidpi**. On top of that, make sure your project is configured to -support :ref:`multiple resolutions `. +support `multiple resolutions `. The project works when run from the editor, but fails to load some files when running from an exported copy. ------------------------------------------------------------------------------------------------------------ @@ -99,9 +99,9 @@ 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 -:ref:`doc_exporting_projects_export_mode` for more information. +`doc_exporting_projects_export_mode` for more information. -On Windows, this can also be due to :ref:`case sensitivity +On Windows, this can also be due to `case sensitivity ` issues. If you reference a resource in your script with a different case than on the filesystem, loading will fail once you export the project. This is because the virtual PCK filesystem is diff --git a/community/contributing/bisecting_regressions.rst b/community/contributing/bisecting_regressions.rst index b6a408d..97c6ff8 100644 --- a/community/contributing/bisecting_regressions.rst +++ b/community/contributing/bisecting_regressions.rst @@ -60,7 +60,7 @@ reproduce the bug. Before bisecting a regression, you need to set up a build environment to compile Godot from source. To do so, read the - :ref:`Compiling ` page for your target platform. + `Compiling ` page for your target platform. (Compiling Godot from source doesn't require C++ programming knowledge.) Note that compiling Godot can take a while on slow hardware (up an hour for @@ -89,7 +89,7 @@ following commit hashes depending on the version: To refer to the latest state of the master branch, you can use ``master`` instead of a commit hash. -:ref:`Get Godot's source code using Git `. Once this +`Get Godot's source code using Git `. Once this is done, in the terminal window, use ``cd`` to reach the Godot repository folder and enter the following command: diff --git a/community/contributing/class_reference_writing_guidelines.rst b/community/contributing/class_reference_writing_guidelines.rst index fcb756a..590d080 100644 --- a/community/contributing/class_reference_writing_guidelines.rst +++ b/community/contributing/class_reference_writing_guidelines.rst @@ -10,7 +10,7 @@ built-in node types. .. seealso:: To learn to submit your changes to the Godot project using the Git version - control system, see :ref:`doc_updating_the_class_reference`. + control system, see `doc_updating_the_class_reference`. The reference for each class is contained in an XML file like the one below: @@ -79,7 +79,7 @@ their documentation by completing or improving the text in these tags: - `` (in its `` tag; arguments don't take separate documentation strings) - `` -Write in a clear and simple language. Always follow the :ref:`writing guidelines +Write in a clear and simple language. Always follow the `writing guidelines ` to keep your descriptions short and easy to read. **Do not leave empty lines** in the descriptions: each line in the XML file will result in a new paragraph, even if it is empty. @@ -107,7 +107,7 @@ This will convert the XML files to the online documentation's format and output errors if anything's wrong. Alternatively, you can build Godot and open the modified page in the built-in -code reference. To learn how to compile the engine, read the :ref:`compilation +code reference. To learn how to compile the engine, read the `compilation guide `. We recommend using a code editor that supports XML files like Vim, Atom, Visual Studio Code, @@ -125,19 +125,19 @@ the text. Here's the list of available tags: +----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ | Tag | Effect | Usage | Result | +============================+======================================+===================================+===================================================+ -| [Class] | Link a class | Move the [Sprite]. | Move the :ref:`class_Sprite`. | +| [Class] | Link a class | Move the [Sprite]. | Move the `class_Sprite`. | +----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ -| [method methodname] | Link to a method in this class | Call [method hide]. | Call :ref:`hide `. | +| [method methodname] | Link to a method in this class | Call [method hide]. | Call `hide `. | +----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ -| [method Class.methodname] | Link to another class's method | Call [method Spatial.hide]. | Call :ref:`hide `. | +| [method Class.methodname] | Link to another class's method | Call [method Spatial.hide]. | Call `hide `. | +----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ -| [member membername] | Link to a member in this class | Get [member scale]. | Get :ref:`scale `. | +| [member membername] | Link to a member in this class | Get [member scale]. | Get `scale `. | +----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ -| [member Class.membername] | Link to another class's member | Get [member Node2D.scale]. | Get :ref:`scale `. | +| [member Class.membername] | Link to another class's member | Get [member Node2D.scale]. | Get `scale `. | +----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ -| [signal signalname] | Link to a signal in this class | Emit [signal renamed]. | Emit :ref:`renamed `. | +| [signal signalname] | Link to a signal in this class | Emit [signal renamed]. | Emit `renamed `. | +----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ -| [signal Class.signalname] | Link to another class's signal | Emit [signal Node.renamed]. | Emit :ref:`renamed `. | +| [signal Class.signalname] | Link to another class's signal | Emit [signal Node.renamed]. | Emit `renamed `. | +----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ | [b] [/b] | Bold | Some [b]bold[/b] text. | Some **bold** text. | +----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ diff --git a/community/contributing/code_style_guidelines.rst b/community/contributing/code_style_guidelines.rst index d53a8f5..ada2774 100644 --- a/community/contributing/code_style_guidelines.rst +++ b/community/contributing/code_style_guidelines.rst @@ -50,7 +50,7 @@ setup clang-format locally to check and automatically fix all your commits. .. seealso:: - These guidelines only cover code formatting. See :ref:`doc_cpp_usage_guidelines` + These guidelines only cover code formatting. See `doc_cpp_usage_guidelines` for a list of language features that are permitted in pull requests. Using clang-format locally @@ -345,7 +345,7 @@ Don't repeat what the code says in a comment. Explain the *why* rather than *how You can use Javadoc-style comments above function or macro definitions. It's recommended to use Javadoc-style comments *only* for methods which are not exposed to scripting. This is because exposed methods should be documented in -the :ref:`class reference XML ` +the `class reference XML ` instead. **Example:** diff --git a/community/contributing/contributing_to_the_documentation.rst b/community/contributing/contributing_to_the_documentation.rst index 9158d69..c7144c4 100644 --- a/community/contributing/contributing_to_the_documentation.rst +++ b/community/contributing/contributing_to_the_documentation.rst @@ -9,7 +9,7 @@ writing or reviewing pages. .. seealso:: If you want to translate pages or the class reference from English to other - languages, read :ref:`doc_editor_and_docs_localization`. + languages, read `doc_editor_and_docs_localization`. Getting started --------------- @@ -20,16 +20,16 @@ files in the `godot-docs GitHub repository request triggers a rebuild of the online documentation upon merging. .. seealso:: For details on Git usage and the pull request workflow, please - refer to the :ref:`doc_pr_workflow` page. Most of what it describes + refer to the `doc_pr_workflow` page. Most of what it describes regarding the main godotengine/godot repository is also valid for the docs repository. .. warning:: The class reference's source files are in the `Godot engine repository `_. We generate - the :ref:`Godot API ` section of this documentation + the `Godot API ` section of this documentation from them. If you want to update the description of a class, its methods, or properties, read - :ref:`doc_updating_the_class_reference`. + `doc_updating_the_class_reference`. What is the Godot documentation ------------------------------- @@ -41,7 +41,7 @@ two game creation tutorials in the Getting Started section. We strive to write factual content in an accessible and well-written language. To contribute, you should also read: -1. The :ref:`doc_docs_writing_guidelines`. There, you will find rules and +1. The `doc_docs_writing_guidelines`. There, you will find rules and recommendations to write in a way that everyone understands. 2. The content guidelines. They explain the principles we follow to write the documentation and the kind of content we accept. @@ -65,10 +65,10 @@ 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 edited here.** They are automatically generated from Godot’s `XML class reference `__. -See :ref:`doc_updating_the_class_reference` for details. +See `doc_updating_the_class_reference` for details. .. seealso:: To build the manual and test changes on your computer, see - :ref:`doc_building_the_manual`. + `doc_building_the_manual`. Editing pages online -------------------- @@ -107,7 +107,7 @@ Before adding a new page, please ensure that it fits in the documentation: `_ or open a new one to see if the page is necessary. 2. Ensure there isn't a page that already covers the topic. -3. Read our :ref:`doc_content_guidelines`. +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``. @@ -130,8 +130,8 @@ Always begin pages with their title and a Sphinx reference name: The reference ``_doc_insert_your_title_here`` and the title should match. -The reference allows linking to this page using the ``:ref:`` format, e.g. -``:ref:`doc_insert_your_title_here``` would link to the above example page (note +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). Write your titles like plain sentences, without capitalizing each word: diff --git a/community/contributing/cpp_usage_guidelines.rst b/community/contributing/cpp_usage_guidelines.rst index 3aaeda1..d61919e 100644 --- a/community/contributing/cpp_usage_guidelines.rst +++ b/community/contributing/cpp_usage_guidelines.rst @@ -31,11 +31,11 @@ modules or GDNative scripts. The guidelines below don't apply to third-party dependencies, although we generally favor small libraries instead of larger solutions. See also - :ref:`doc_best_practices_for_engine_contributors`. + `doc_best_practices_for_engine_contributors`. .. seealso:: - See :ref:`doc_code_style_guidelines` for formatting guidelines. + See `doc_code_style_guidelines` for formatting guidelines. Disallowed features ------------------- @@ -50,7 +50,7 @@ Standard Template Library We don't allow using the `STL `__ as Godot provides its own data types (among other things). -See :ref:`doc_faq_why_not_stl` for more information. +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: @@ -102,5 +102,5 @@ guards instead of ``#pragma once`` in new files. .. seealso:: - See :ref:`doc_code_style_guidelines_header_includes` for guidelines on sorting + See `doc_code_style_guidelines_header_includes` for guidelines on sorting includes in C++ and Objective-C files. diff --git a/community/contributing/docs_writing_guidelines.rst b/community/contributing/docs_writing_guidelines.rst index 98626bc..cba63f1 100644 --- a/community/contributing/docs_writing_guidelines.rst +++ b/community/contributing/docs_writing_guidelines.rst @@ -34,7 +34,7 @@ There are 3 rules to describe classes: .. seealso:: - See the :ref:`content guidelines ` for information + See the `content guidelines ` for information on the types of documentation you can write in the official documentation. 7 rules for clear English diff --git a/community/contributing/documentation_guidelines.rst b/community/contributing/documentation_guidelines.rst index 9320710..c694eee 100644 --- a/community/contributing/documentation_guidelines.rst +++ b/community/contributing/documentation_guidelines.rst @@ -21,22 +21,22 @@ in a pull request and getting it merged will trigger a rebuild of the online documentation. .. seealso:: For details on Git usage and the pull request workflow, please - refer to the :ref:`doc_pr_workflow` page. Most of what it + refer to the `doc_pr_workflow` page. Most of what it describes regarding the main godotengine/godot repository is also valid for the docs repository. .. warning:: The class reference's source files are in the `Godot engine repository - `_. We generate the :ref:`Godot API + `_. We generate the `Godot API ` section of this documentation from them. If you want to update the description of a class, its methods, or properties, read - :ref:`doc_updating_the_class_reference`. + `doc_updating_the_class_reference`. .. warning:: If you want to edit the **API reference**, please note that it should *not* be done in the godot-docs repository. Instead, you should edit the ``doc/classes/*`` XML files of Godot's main repository. These files are then later used to generate the in-editor documentation as well as the API reference of the - online docs. Read more here: :ref:`doc_updating_the_class_reference`. + online docs. Read more here: `doc_updating_the_class_reference`. The 'Edit on GitHub' link ------------------------- @@ -70,7 +70,7 @@ What makes good documentation? Documentation should be well written in plain English, using well-formed sentences and various levels of sections and subsections. It should be clear -and objective. Also, have a look at the :ref:`doc_docs_writing_guidelines`. +and objective. Also, have a look at the `doc_docs_writing_guidelines`. We differentiate tutorial pages from other documentation pages by these definitions: @@ -98,8 +98,8 @@ Always begin pages with their title and a Sphinx reference name: Insert your title here ====================== -The reference allows linking to this page using the ``:ref:`` format, e.g. -``:ref:`doc_insert_your_title_here``` would link to the above example page +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). Also, avoid American CamelCase titles: title's first word should begin diff --git a/community/contributing/editor_and_docs_localization.rst b/community/contributing/editor_and_docs_localization.rst index d97c4b4..759dddb 100644 --- a/community/contributing/editor_and_docs_localization.rst +++ b/community/contributing/editor_and_docs_localization.rst @@ -172,14 +172,14 @@ translating. 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 - page :ref:`doc_nodes_and_scenes`. + 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 table of contents for the online version. You can therefore locate the source string corresponding to the brief description of a given class to find the 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 - :ref:`class_Node2D` class would have the source string location + `class_Node2D` class would have the source string location ``doc/classes/Node2D.xml``. A handy tool to locate specific pages/classes is to use Weblate's advanced @@ -272,16 +272,16 @@ external links, etc. Here are some examples:: |supported| Backwards-compatible new features (backported from the ``master`` branch) as well as bug, security, and platform support fixes. - # The :ref: Sphinx "role" is used for internal references to other pages of + # The Sphinx "role" is used for internal references to other pages of # the documentation. # It can be used with only the reference name of a page (which should not be # changed), in which case the title of that page will be displayed: - See :ref:`doc_ways_to_contribute`. + See `doc_ways_to_contribute`. # Or it can be used with an optional custom title, which should thus be translated: - See :ref:`how to contribute `. + See `how to contribute `. # You may encounter other Sphinx roles, such as :kbd: used for shortcut keys. # You can translate the content between backticks to match the usual key names, @@ -327,7 +327,7 @@ breaks if they are not part of the original translation. .. seealso:: - See our documentation for class reference writers for the :ref:`list of + See our documentation for class reference writers for the `list of BBCode-like tags ` which are used throughout the class reference. @@ -357,7 +357,7 @@ upload mode. version. If you want to test changes locally (especially for the editor translation), you -can use the downloaded PO file and :ref:`compile Godot from source `. +can use the downloaded PO file and `compile Godot from source `. Rename the editor translation PO file to ``.po`` (e.g. ``eo.po`` for Esperanto) and place it in the ``editor/translations/`` folder @@ -386,7 +386,7 @@ documentation translations are synced from Weblate. To translate an image, you should first locate it in the original English documentation. To do so, browse the relevant page in the docs, e.g. -:ref:`doc_intro_to_the_editor_interface`. Click the "Edit on GitHub" link in the +`doc_intro_to_the_editor_interface`. Click the "Edit on GitHub" link in the top right corner: .. image:: img/l10n_08_edit_on_github.png @@ -413,4 +413,4 @@ original image in the ``images`` subfolder 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``. -Repeat this for other images and :ref:`make a Pull Request `. +Repeat this for other images and `make a Pull Request `. diff --git a/community/contributing/pr_workflow.rst b/community/contributing/pr_workflow.rst index 8f0d17f..77dd883 100644 --- a/community/contributing/pr_workflow.rst +++ b/community/contributing/pr_workflow.rst @@ -236,7 +236,7 @@ You will then be back to the original state of your branch before calling 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 :ref:`dedicated +is to use an *interactive rebase* on the upstream branch. See the `dedicated section ` for instructions. .. tip:: If at any time you want to *reset* a local branch to a given commit or branch, diff --git a/community/contributing/testing_pull_requests.rst b/community/contributing/testing_pull_requests.rst index b2ff558..a01a886 100644 --- a/community/contributing/testing_pull_requests.rst +++ b/community/contributing/testing_pull_requests.rst @@ -23,7 +23,7 @@ depending on whether you have a GitHub account or not. Due to a GitHub Actions limitation, builds are only available for 90 days after the pull request was last updated. If you still wish to try a pull request locally, you can - :ref:`compile the pull request branch from source ` + `compile the pull request branch from source ` instead. If you have a GitHub account @@ -100,5 +100,5 @@ by Godot's GitHub Actions setup. .. image:: img/testing_pull_requests_fork_zip.png -- Extract the ZIP archive and follow the :ref:`compiling ` instructions +- Extract the ZIP archive and follow the `compiling ` instructions for your operating system. diff --git a/community/contributing/updating_the_class_reference.rst b/community/contributing/updating_the_class_reference.rst index 891e163..6c72f9c 100644 --- a/community/contributing/updating_the_class_reference.rst +++ b/community/contributing/updating_the_class_reference.rst @@ -5,7 +5,7 @@ Contributing to the class reference .. highlight:: shell -The class reference is available online in the :ref:`classes ` +The class reference is available online in the `classes ` section of the documentation and in the Godot editor, from the help menu. In the class reference, some methods, variables, and signals lack descriptions. @@ -20,13 +20,13 @@ taking care of a given class. .. seealso:: - You can find the writing guidelines for the class reference :ref:`here `. + You can find the writing guidelines for the class reference `here `. For details on Git usage and the pull request workflow, please - refer to the :ref:`doc_pr_workflow` page. + refer to the `doc_pr_workflow` page. If you want to translate the class reference from English to another - language, see :ref:`doc_editor_and_docs_localization`. + language, see `doc_editor_and_docs_localization`. This guide is also available as a `video tutorial on YouTube `_. @@ -44,7 +44,7 @@ repository: `doc/classes/ files in the ``modules//doc_classes/`` directory instead. .. warning:: Always edit the API reference through these source XML files. Do - not edit the generated ``.rst`` files :ref:`in the online documentation + not edit the generated ``.rst`` files `in the online documentation `, hosted in the `godot-docs `_ repository. @@ -56,7 +56,7 @@ repository: `doc/classes/ Also, it doesn't allow you to test your changes in the engine or with validation scripts as described in - :ref:`doc_class_reference_writing_guidelines_editing_xml`. + `doc_class_reference_writing_guidelines_editing_xml`. Updating the documentation template ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -64,7 +64,7 @@ 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/``. To do so, you first need to compile Godot. See the -:ref:`doc_introduction_to_the_buildsystem` page to learn how. Then, execute 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. For example, if you're on 64-bit Linux, the command is:: diff --git a/community/contributing/ways_to_contribute.rst b/community/contributing/ways_to_contribute.rst index ea22647..7263340 100644 --- a/community/contributing/ways_to_contribute.rst +++ b/community/contributing/ways_to_contribute.rst @@ -89,11 +89,11 @@ A good place to start is by searching for issues tagged as on GitHub. .. seealso:: Technical details about the PR workflow are outlined in a - specific section, :ref:`doc_pr_workflow`. + specific section, `doc_pr_workflow`. Details about the code style guidelines and the ``clang-format`` tool used to enforce them are outlined in - :ref:`doc_code_style_guidelines`. + `doc_code_style_guidelines`. All pull requests must go through a review process before being accepted. Depending on the scope of the changes, it may take some time for a maintainer @@ -125,7 +125,7 @@ Testing development versions To help with the testing, you have several possibilities: - Compile the engine from source yourself, following the instructions of the - :ref:`Compiling ` page for your platform. + `Compiling ` page for your platform. - Test official pre-release binaries when they are announced (usually on the blog and other community platforms), such as alpha, beta and release candidate (RC) builds. @@ -196,18 +196,18 @@ There are two separate resources referred to as "documentation" in Godot: - **The class reference.** This is the documentation for the complete Godot API as exposed to GDScript and the other scripting languages. It can be consulted - offline, directly in Godot's code editor, or online at :ref:`Godot API + offline, directly in Godot's code editor, or online at `Godot API `. To contribute to the class reference, you have to edit the XML file corresponding to the class and make a pull request. - See :ref:`doc_updating_the_class_reference` and - :ref:`doc_class_reference_writing_guidelines` for more details. + See `doc_updating_the_class_reference` and + `doc_class_reference_writing_guidelines` for more details. - **The tutorials and engine documentation and its translations.** This is the part you are reading now, which is distributed in the HTML format. Its contents are generated from plain text files in the reStructured Text (rst) format, to which you can contribute via pull requests on the `godot-docs `_ GitHub repository. - See :ref:`doc_contributing_to_the_documentation` for more details. + See `doc_contributing_to_the_documentation` for more details. Contributing translations ------------------------- @@ -216,4 +216,4 @@ To make Godot accessible to everyone, including users who may prefer resources in their native language instead of English, our community helps translate both the Godot editor and its documentation in many languages. -See :ref:`doc_editor_and_docs_localization` for more details. +See `doc_editor_and_docs_localization` for more details. diff --git a/development/compiling/compiling_for_android.rst b/development/compiling/compiling_for_android.rst index fcd5cd3..d900b22 100644 --- a/development/compiling/compiling_for_android.rst +++ b/development/compiling/compiling_for_android.rst @@ -8,7 +8,7 @@ Compiling for Android .. seealso:: This page describes how to compile Android export template binaries from source. - If you're looking to export your project to Android instead, read :ref:`doc_exporting_for_android`. + If you're looking to export your project to Android instead, read `doc_exporting_for_android`. Note ---- @@ -18,7 +18,7 @@ enough. Compiling the Android APK manually is mostly useful for custom builds or custom packages for the deployer. Also, you still need to follow the steps mentioned in the -:ref:`doc_exporting_for_android` tutorial before attempting to build +`doc_exporting_for_android` tutorial before attempting to build a custom export template. Requirements @@ -41,10 +41,10 @@ For compiling under Windows, Linux or macOS, the following is required: - You can download a build from `ojdkbuild `_. .. seealso:: To get the Godot source code for compiling, see - :ref:`doc_getting_source`. + `doc_getting_source`. For a general overview of SCons usage for Godot, see - :ref:`doc_introduction_to_the_buildsystem`. + `doc_introduction_to_the_buildsystem`. .. _doc_android_setting_up_the_buildsystem: @@ -209,7 +209,7 @@ Platform doesn't appear in SCons 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 :ref:`Setting up the buildsystem ` +See `Setting up the buildsystem ` for more information. Application not installed diff --git a/development/compiling/compiling_for_ios.rst b/development/compiling/compiling_for_ios.rst index 82cf9bc..f8edb92 100644 --- a/development/compiling/compiling_for_ios.rst +++ b/development/compiling/compiling_for_ios.rst @@ -8,7 +8,7 @@ Compiling for iOS .. seealso:: This page describes how to compile iOS export template binaries from source. - If you're looking to export your project to iOS instead, read :ref:`doc_exporting_for_ios`. + If you're looking to export your project to iOS instead, read `doc_exporting_for_ios`. Requirements ------------ @@ -19,10 +19,10 @@ Requirements - 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 - :ref:`doc_getting_source`. + `doc_getting_source`. For a general overview of SCons usage for Godot, see - :ref:`doc_introduction_to_the_buildsystem`. + `doc_introduction_to_the_buildsystem`. Compiling --------- @@ -79,7 +79,7 @@ Run --- To run on a device or simulator, follow these instructions: -:ref:`doc_exporting_for_ios`. +`doc_exporting_for_ios`. Replace or add your executable to the Xcode project, and change the "executable name" property on Info.plist accordingly if you use an diff --git a/development/compiling/compiling_for_osx.rst b/development/compiling/compiling_for_osx.rst index 0616cd8..fb0bb31 100644 --- a/development/compiling/compiling_for_osx.rst +++ b/development/compiling/compiling_for_osx.rst @@ -8,7 +8,7 @@ Compiling for macOS .. note:: This page describes how to compile macOS editor and export template binaries from source. - If you're looking to export your project to macOS instead, read :ref:`doc_exporting_for_macos`. + If you're looking to export your project to macOS instead, read `doc_exporting_for_macos`. Requirements ------------ @@ -36,10 +36,10 @@ For compiling under macOS, the following is required: sudo port install scons yasm .. seealso:: To get the Godot source code for compiling, see - :ref:`doc_getting_source`. + `doc_getting_source`. For a general overview of SCons usage for Godot, see - :ref:`doc_introduction_to_the_buildsystem`. + `doc_introduction_to_the_buildsystem`. Compiling --------- @@ -65,7 +65,7 @@ manager. .. note:: If you want to use separate editor settings for your own Godot builds and official releases, you can enable - :ref:`doc_data_paths_self_contained_mode` by creating a file called + `doc_data_paths_self_contained_mode` by creating a file called ``._sc_`` or ``_sc_`` in the ``bin/`` folder. To create an ``.app`` bundle like in the official builds, you need to use the @@ -86,7 +86,7 @@ projects in an automated manner, use:: scons platform=server tools=yes target=release_debug --jobs=$(sysctl -n hw.logicalcpu) To compile a debug *server* build which can be used with -:ref:`remote debugging tools `, use:: +`remote debugging tools `, use:: scons platform=server tools=no target=release_debug --jobs=$(sysctl -n hw.logicalcpu) diff --git a/development/compiling/compiling_for_uwp.rst b/development/compiling/compiling_for_uwp.rst index 32e2e09..ec651e4 100644 --- a/development/compiling/compiling_for_uwp.rst +++ b/development/compiling/compiling_for_uwp.rst @@ -8,13 +8,13 @@ Compiling for Universal Windows Platform .. seealso:: This page describes how to compile UWP export template binaries from source. - If you're looking to export your project to UWP instead, read :ref:`doc_exporting_for_uwp`. + If you're looking to export your project to UWP instead, read `doc_exporting_for_uwp`. Requirements ------------ -- SCons 3.0+ (see :ref:`doc_compiling_for_windows` for more details). -- Visual Studio 2017 or later. See :ref:`doc_compiling_for_windows` about the +- SCons 3.0+ (see `doc_compiling_for_windows` for more details). +- Visual Studio 2017 or later. See `doc_compiling_for_windows` about the caveats of installing it and the various prompts. - Windows 10 SDK (can be selected in Visual Studio installation). - `ANGLE source `__. Use the @@ -32,16 +32,16 @@ Requirements the new build instructions. .. seealso:: To get the Godot source code for compiling, see - :ref:`doc_getting_source`. + `doc_getting_source`. For a general overview of SCons usage for Godot, see - :ref:`doc_introduction_to_the_buildsystem`. + `doc_introduction_to_the_buildsystem`. Compiling --------- You need to open a proper Visual Studio prompt for the target architecture -you want to build. Check :ref:`doc_compiling_for_windows` to see how these +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) diff --git a/development/compiling/compiling_for_web.rst b/development/compiling/compiling_for_web.rst index 3a95a4c..66304cc 100644 --- a/development/compiling/compiling_for_web.rst +++ b/development/compiling/compiling_for_web.rst @@ -6,7 +6,7 @@ Compiling for the Web .. seealso:: This page describes how to compile HTML5 editor and export template binaries from source. - If you're looking to export your project to HTML5 instead, read :ref:`doc_exporting_for_web`. + If you're looking to export your project to HTML5 instead, read `doc_exporting_for_web`. .. highlight:: shell @@ -20,10 +20,10 @@ To compile export templates for the Web, the following is required: - `SCons 3.0+ `__ build system. .. seealso:: To get the Godot source code for compiling, see - :ref:`doc_getting_source`. + `doc_getting_source`. For a general overview of SCons usage for Godot, see - :ref:`doc_introduction_to_the_buildsystem`. + `doc_introduction_to_the_buildsystem`. Building export templates ------------------------- @@ -39,7 +39,7 @@ 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 :ref:`JavaScript singleton ` will be built +By default, the `JavaScript singleton ` will be built into the engine. Official export templates also have the JavaScript singleton enabled. Since ``eval()`` calls can be a security concern, the ``javascript_eval`` option can be used to build without the singleton:: @@ -66,7 +66,7 @@ Threads and GDNative The default export templates do not include threads and GDNative support for performance and compatibility reasons. See the -:ref:`export page ` for more info. +`export page ` for more info. You can build the export templates using the option ``threads_enabled=yes`` or ``gdnative_enabled=yes`` to enable threads or GDNative support:: @@ -105,5 +105,5 @@ 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 :ref:`export page ` for the web +Refer to the `export page ` for the web server requirements. diff --git a/development/compiling/compiling_for_windows.rst b/development/compiling/compiling_for_windows.rst index 7347bde..bea8047 100644 --- a/development/compiling/compiling_for_windows.rst +++ b/development/compiling/compiling_for_windows.rst @@ -8,7 +8,7 @@ Compiling for Windows .. seealso:: This page describes how to compile Windows editor and export template binaries from source. - If you're looking to export your project to Windows instead, read :ref:`doc_exporting_for_windows`. + If you're looking to export your project to Windows instead, read `doc_exporting_for_windows`. Requirements ------------ @@ -41,10 +41,10 @@ For compiling under Windows, the following is required: `pip3 install scons` in its shell. .. seealso:: To get the Godot source code for compiling, see - :ref:`doc_getting_source`. + `doc_getting_source`. For a general overview of SCons usage for Godot, see - :ref:`doc_introduction_to_the_buildsystem`. + `doc_introduction_to_the_buildsystem`. Setting up SCons ---------------- @@ -91,7 +91,7 @@ a **Repair** option, which won't let you install C++ tools. Downloading Godot's source -------------------------- -Refer to :ref:`doc_getting_source` for detailed instructions. +Refer to `doc_getting_source` for detailed instructions. The tutorial will assume from now on that you placed the source code in ``C:\godot``. @@ -165,7 +165,7 @@ dependencies. Running 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 - :ref:`doc_data_paths_self_contained_mode` by creating a file called + `doc_data_paths_self_contained_mode` by creating a file called ``._sc_`` or ``_sc_`` in the ``bin/`` folder. Development in Visual Studio @@ -186,7 +186,7 @@ the ``vsproj=yes`` parameter, like this:: You will be able to open Godot's source in a Visual Studio solution now, and able to build Godot using Visual Studio's **Build** button. -.. seealso:: See :ref:`doc_configuring_an_ide_vs` for further details. +.. seealso:: See `doc_configuring_an_ide_vs` for further details. Cross-compiling for Windows from other operating systems -------------------------------------------------------- diff --git a/development/compiling/compiling_for_x11.rst b/development/compiling/compiling_for_x11.rst index 31e94d8..0a369a6 100644 --- a/development/compiling/compiling_for_x11.rst +++ b/development/compiling/compiling_for_x11.rst @@ -8,7 +8,7 @@ Compiling for X11 (Linux, \*BSD) .. seealso:: This page describes how to compile Linux editor and export template binaries from source. - If you're looking to export your project to Linux instead, read :ref:`doc_exporting_for_linux`. + If you're looking to export your project to Linux instead, read `doc_exporting_for_linux`. Requirements ------------ @@ -32,10 +32,10 @@ required: - *Optional* - yasm (for WebM SIMD optimizations). .. seealso:: To get the Godot source code for compiling, see - :ref:`doc_getting_source`. + `doc_getting_source`. For a general overview of SCons usage for Godot, see - :ref:`doc_introduction_to_the_buildsystem`. + `doc_introduction_to_the_buildsystem`. Distro-specific one-liners ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -139,7 +139,7 @@ manager. .. note:: If you want to use separate editor settings for your own Godot builds and official releases, you can enable - :ref:`doc_data_paths_self_contained_mode` by creating a file called + `doc_data_paths_self_contained_mode` by creating a file called ``._sc_`` or ``_sc_`` in the ``bin/`` folder. Compiling a headless/server build @@ -151,7 +151,7 @@ projects in an automated manner, use:: scons -j8 platform=server tools=yes target=release_debug To compile a debug *server* build which can be used with -:ref:`remote debugging tools `, use:: +`remote debugging tools `, use:: scons -j8 platform=server tools=no target=release_debug diff --git a/development/compiling/compiling_with_mono.rst b/development/compiling/compiling_with_mono.rst index 137971c..b594c3d 100644 --- a/development/compiling/compiling_with_mono.rst +++ b/development/compiling/compiling_with_mono.rst @@ -118,7 +118,7 @@ the following files in the ``bin`` directory: for the editor and for export templates. This directory is important for proper functioning and must be distributed together with Godot. More details about this directory in - :ref:`Data directory`. + `Data directory`. Examples -------- @@ -249,7 +249,7 @@ to the Gradle project. Once you've built Mono, you can proceed to build Godot with the instructions described in this page and the -:ref:`Compiling for Android` page. +`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"`` (This path may be different on your system). @@ -259,7 +259,7 @@ Targeting iOS Once you've built Mono, you can proceed to build Godot with the instructions described in this page and the -:ref:`Compiling for iOS` page. +`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"`` (This path may be different on your system). @@ -308,7 +308,7 @@ Building for WebAssembly currently involves the same process regardless of wheth Once you've built Mono, you can proceed to build Godot with the instructions described in this page and the -:ref:`Compiling for the Web` page. +`Compiling for the Web` page. Make sure to let SCons know about the location of the Mono runtime you've just built, e.g.: ``scons [...] mono_prefix="$HOME/mono-installs/wasm-runtime-release"`` (This path may be different on your system). diff --git a/development/compiling/getting_source.rst b/development/compiling/getting_source.rst index 36e4e42..647e58f 100644 --- a/development/compiling/getting_source.rst +++ b/development/compiling/getting_source.rst @@ -8,7 +8,7 @@ Getting the source Downloading the Godot source code --------------------------------- -Before :ref:`getting into the SCons build system ` +Before `getting into the SCons build system ` and compiling Godot, you need to actually download the Godot source code. The source code is available on `GitHub `__ @@ -16,7 +16,7 @@ and while you can manually download it via the website, in general you want to 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 :ref:`Pull Request workflow `. +follow the instructions from the `Pull Request workflow `. If you don't know much about ``git`` yet, there are a great number of `tutorials `__ available on various websites. @@ -51,4 +51,4 @@ after the ``--branch`` (or just ``-b``) argument:: There are also generally branches besides ``master`` for each major version. After downloading the Godot source code, -you can :ref:`continue to compiling Godot `. +you can `continue to compiling Godot `. diff --git a/development/compiling/introduction_to_the_buildsystem.rst b/development/compiling/introduction_to_the_buildsystem.rst index 1390759..919e0f7 100644 --- a/development/compiling/introduction_to_the_buildsystem.rst +++ b/development/compiling/introduction_to_the_buildsystem.rst @@ -39,10 +39,10 @@ if you are planning to build Godot yourself. Setup ----- -Please refer to the documentation for :ref:`doc_compiling_for_android`, -:ref:`doc_compiling_for_ios`, :ref:`doc_compiling_for_osx`, -:ref:`doc_compiling_for_uwp`, :ref:`doc_compiling_for_web`, -:ref:`doc_compiling_for_windows` and :ref:`doc_compiling_for_x11`. +Please refer to the documentation for `doc_compiling_for_android`, +`doc_compiling_for_ios`, `doc_compiling_for_osx`, +`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 @@ -210,7 +210,7 @@ directory paths containing such modules: .. seealso:: - :ref:`doc_custom_modules_in_c++` + `doc_custom_modules_in_c++` Cleaning generated files ------------------------ @@ -255,7 +255,7 @@ source to initialize any SCons build options passed via the command line: extra_suffix = "game_title" You can also disable some of the builtin modules before compiling, saving some -time it takes to build the engine. See :ref:`doc_optimizing_for_size` page for more details. +time it takes to build the engine. See `doc_optimizing_for_size` page for more details. .. seealso:: diff --git a/development/compiling/optimizing_for_size.rst b/development/compiling/optimizing_for_size.rst index 113d04e..8681aa7 100644 --- a/development/compiling/optimizing_for_size.rst +++ b/development/compiling/optimizing_for_size.rst @@ -40,7 +40,7 @@ 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 (which is useful for troubleshooting the cause of a crash). -:ref:`C++ profilers ` will also no longer be able to display +`C++ profilers ` will also no longer be able to display function names (this does not affect the built-in GDScript profiler). .. note:: @@ -215,4 +215,4 @@ following: .. seealso:: - :ref:`doc_overriding_build_options`. + `doc_overriding_build_options`. diff --git a/development/cpp/binding_to_external_libraries.rst b/development/cpp/binding_to_external_libraries.rst index 9025a8b..4509f78 100644 --- a/development/cpp/binding_to_external_libraries.rst +++ b/development/cpp/binding_to_external_libraries.rst @@ -6,7 +6,7 @@ Binding to external libraries Modules ------- -The Summator example in :ref:`doc_custom_modules_in_c++` is great for small, +The Summator example in `doc_custom_modules_in_c++` is great for small, custom modules, but what if you want to use a larger, external library? Let's look at an example using `Festival `_, a speech synthesis (text-to-speech) library written in C++. diff --git a/development/cpp/common_engine_methods_and_macros.rst b/development/cpp/common_engine_methods_and_macros.rst index 17af34e..077d773 100644 --- a/development/cpp/common_engine_methods_and_macros.rst +++ b/development/cpp/common_engine_methods_and_macros.rst @@ -34,7 +34,7 @@ described below. Format a string --------------- -The ``vformat()`` function returns a formatted :ref:`class_String`. It behaves +The ``vformat()`` function returns a formatted `class_String`. It behaves in a way similar to C's ``sprintf()``: .. code-block:: cpp diff --git a/development/cpp/configuring_an_ide/android_studio.rst b/development/cpp/configuring_an_ide/android_studio.rst index 7e84193..6422144 100644 --- a/development/cpp/configuring_an_ide/android_studio.rst +++ b/development/cpp/configuring_an_ide/android_studio.rst @@ -22,7 +22,7 @@ Importing the project - Navigate to ``/platform/android/java`` and select the ``settings.gradle`` file. - Android Studio will import and index the project. -- To build the project, follow the :ref:`compiling instructions `. +- To build the project, follow the `compiling instructions `. If you run into any issues, ask for help in one of `Godot's community channels `__. diff --git a/development/cpp/configuring_an_ide/clion.rst b/development/cpp/configuring_an_ide/clion.rst index 88febf2..83dae9b 100644 --- a/development/cpp/configuring_an_ide/clion.rst +++ b/development/cpp/configuring_an_ide/clion.rst @@ -11,7 +11,7 @@ Importing the project 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 :ref:`Android Studio ` +there is a ``CMakeLists.txt`` configuration for `Android Studio ` which can also be used by CLion. - From the CLion's welcome window choose the option to import an existing diff --git a/development/cpp/configuring_an_ide/code_blocks.rst b/development/cpp/configuring_an_ide/code_blocks.rst index 2fa1d37..9140592 100644 --- a/development/cpp/configuring_an_ide/code_blocks.rst +++ b/development/cpp/configuring_an_ide/code_blocks.rst @@ -61,7 +61,7 @@ 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 :ref:`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. @@ -114,7 +114,7 @@ It should automatically select the project folder; so simply click **Open**. By Code style configuration ------------------------ -Before editing any files, remember that all code needs to comply with the :ref:`doc_code_style_guidelines`. One important difference with Godot is the use of tabs for indents. Therefore, the key default editor setting that needs to be changed in Code::Blocks is to enable tabs for indents. This setting can be found by selecting **Settings > Editor**. +Before editing any files, remember that all code needs to comply with the `doc_code_style_guidelines`. One important difference with Godot is the use of tabs for indents. Therefore, the key default editor setting that needs to be changed in Code::Blocks is to enable tabs for indents. This setting can be found by selecting **Settings > Editor**. .. figure:: img/code_blocks_update_editor_settings.png :figclass: figure-w480 diff --git a/development/cpp/configuring_an_ide/index.rst b/development/cpp/configuring_an_ide/index.rst index c0be071..82d7154 100644 --- a/development/cpp/configuring_an_ide/index.rst +++ b/development/cpp/configuring_an_ide/index.rst @@ -2,7 +2,7 @@ Configuring an IDE ================== We assume that you have already `cloned `_ -and :ref:`compiled ` Godot. +and `compiled ` Godot. 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 diff --git a/development/cpp/configuring_an_ide/kdevelop.rst b/development/cpp/configuring_an_ide/kdevelop.rst index 914e29a..a3c2561 100644 --- a/development/cpp/configuring_an_ide/kdevelop.rst +++ b/development/cpp/configuring_an_ide/kdevelop.rst @@ -56,7 +56,7 @@ Importing the project +-----------------+------------------------------------------------------------------------------+ | Executable | **scons** | +-----------------+------------------------------------------------------------------------------+ - | Arguments | See :ref:`doc_introduction_to_the_buildsystem` for a full list of arguments. | + | Arguments | See `doc_introduction_to_the_buildsystem` for a full list of arguments. | +-----------------+------------------------------------------------------------------------------+ .. figure:: img/kdevelop_buildconfig.png diff --git a/development/cpp/configuring_an_ide/qt_creator.rst b/development/cpp/configuring_an_ide/qt_creator.rst index 9f0b8b1..5d6b9d1 100644 --- a/development/cpp/configuring_an_ide/qt_creator.rst +++ b/development/cpp/configuring_an_ide/qt_creator.rst @@ -58,7 +58,7 @@ Importing the project +-----------+------------------------------------------------------------------------------+ | Command | **scons** | +-----------+------------------------------------------------------------------------------+ - | Arguments | See :ref:`doc_introduction_to_the_buildsystem` for a full list of arguments. | + | Arguments | See `doc_introduction_to_the_buildsystem` for a full list of arguments. | +-----------+------------------------------------------------------------------------------+ .. figure:: img/qtcreator-set-scons-command.png @@ -85,12 +85,12 @@ Debugging the project :align: center To learn more about command line arguments, refer to the -:ref:`command line tutorial `. +`command line tutorial `. Code style configuration ------------------------ -Developers must follow the project's :ref:`code style ` +Developers must follow the project's `code style ` and the IDE should help them follow it. By default, Qt Creator uses spaces for indentation which doesn't match the Godot code style guidelines. You can change this behavior by changing the **Code Style** in **Tools > Options > C++**. diff --git a/development/cpp/configuring_an_ide/visual_studio.rst b/development/cpp/configuring_an_ide/visual_studio.rst index 4a46351..471ed4a 100644 --- a/development/cpp/configuring_an_ide/visual_studio.rst +++ b/development/cpp/configuring_an_ide/visual_studio.rst @@ -53,7 +53,7 @@ project manager opens a project, the initial process is terminated and the debug :align: center To learn more about command line arguments, refer to the -:ref:`command line tutorial `. +`command line tutorial `. 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. diff --git a/development/cpp/configuring_an_ide/visual_studio_code.rst b/development/cpp/configuring_an_ide/visual_studio_code.rst index 468e1fe..8402aab 100644 --- a/development/cpp/configuring_an_ide/visual_studio_code.rst +++ b/development/cpp/configuring_an_ide/visual_studio_code.rst @@ -4,7 +4,7 @@ Visual Studio Code ================== `Visual Studio Code `_ is a free cross-platform code editor -by `Microsoft `_ (not to be confused with :ref:`doc_configuring_an_ide_vs`). +by `Microsoft `_ (not to be confused with `doc_configuring_an_ide_vs`). Importing the project --------------------- @@ -73,7 +73,7 @@ js Windows An example of a filled out ``tasks.json``. Arguments can be different based on your own setup and needs. See -:ref:`doc_introduction_to_the_buildsystem` for a full list of arguments. +`doc_introduction_to_the_buildsystem` for a full list of arguments. Debugging the project --------------------- @@ -174,7 +174,7 @@ js Windows If you encounter issues with lldb, you may consider using gdb (see the X11_gdb configuration). - Do note that lldb may work better with llvm-based builds. See :ref:`doc_compiling_for_x11` for further information. + 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. diff --git a/development/cpp/configuring_an_ide/xcode.rst b/development/cpp/configuring_an_ide/xcode.rst index 4fcf4cc..d27333f 100644 --- a/development/cpp/configuring_an_ide/xcode.rst +++ b/development/cpp/configuring_an_ide/xcode.rst @@ -21,7 +21,7 @@ Importing the project +------------+------------------------------------------------------------------------------+ | Build Tool | A full path to the **scons** executable, e.g. **/usr/local/bin/scons** | +------------+------------------------------------------------------------------------------+ - | Arguments | See :ref:`doc_introduction_to_the_buildsystem` for a full list of arguments. | + | Arguments | See `doc_introduction_to_the_buildsystem` for a full list of arguments. | +------------+------------------------------------------------------------------------------+ | Directory | A full path to the Godot root folder | +------------+------------------------------------------------------------------------------+ diff --git a/development/cpp/custom_audiostreams.rst b/development/cpp/custom_audiostreams.rst index 33d9095..878f1c7 100644 --- a/development/cpp/custom_audiostreams.rst +++ b/development/cpp/custom_audiostreams.rst @@ -17,7 +17,7 @@ its own internal custom AudioStreamPlayback which translates AudioStream into PCM data. This guide assumes the reader knows how to create C++ modules. If not, refer to this guide -:ref:`doc_custom_modules_in_c++`. +`doc_custom_modules_in_c++`. References: ~~~~~~~~~~~ diff --git a/development/cpp/custom_godot_servers.rst b/development/cpp/custom_godot_servers.rst index ebf6fa3..eac6161 100644 --- a/development/cpp/custom_godot_servers.rst +++ b/development/cpp/custom_godot_servers.rst @@ -13,7 +13,7 @@ engine and other modules. In addition, the server claims ownership for its RID allocations. This guide assumes the reader knows how to create C++ modules and Godot -data types. If not, refer to :ref:`doc_custom_modules_in_c++`. +data types. If not, refer to `doc_custom_modules_in_c++`. References ~~~~~~~~~~~ @@ -315,7 +315,7 @@ object-oriented C code. References ~~~~~~~~~~~ -- :ref:`RID` +- `RID` - `core/rid.h `__ Registering the class in GDScript diff --git a/development/cpp/custom_modules_in_cpp.rst b/development/cpp/custom_modules_in_cpp.rst index e1e84b0..6240207 100644 --- a/development/cpp/custom_modules_in_cpp.rst +++ b/development/cpp/custom_modules_in_cpp.rst @@ -34,7 +34,7 @@ instead. Adding C++ modules can be useful in the following scenarios: Creating a new module --------------------- -Before creating a module, make sure to :ref:`download the source code of Godot +Before creating a module, make sure to `download the source code of Godot and compile it `. To create a new module, the first step is creating a directory inside @@ -243,7 +243,7 @@ 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 - :ref:`doc_binding_to_external_libraries` for details about binding to + `doc_binding_to_external_libraries` for details about binding to external libraries. .. warning:: If your module is meant to be accessed from the running project @@ -251,7 +251,7 @@ The output will be ``60``. template you plan to use, then specify the path to the custom template in each export preset. Otherwise, you'll get errors when running the project as the module isn't compiled in the export - template. See the :ref:`Compiling ` pages + template. See the `Compiling ` pages for more information. Compiling a module externally @@ -303,7 +303,7 @@ and compile them accordingly, including our "summator" module. .. seealso:: - :ref:`Introduction to the buildsystem - Custom modules build option `. + `Introduction to the buildsystem - Custom modules build option `. Improving the build system for development ------------------------------------------ @@ -312,7 +312,7 @@ Improving the build system for development This shared library support is not designed to support distributing a module to other users without recompiling the engine. For that purpose, use - :ref:`GDNative ` instead. + `GDNative ` instead. So far, we defined a clean SCsub that allows us to add the sources of our new module as part of the Godot binary. @@ -494,7 +494,7 @@ 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 :ref:`doc_updating_the_class_reference` and recompile the engine. +Edit the file(s) following `doc_updating_the_class_reference` and recompile the engine. Once the compilation process is finished, the docs will become accessible within the engine's built-in documentation system. @@ -525,7 +525,7 @@ Similarly to how you can write self-contained documentation within a module, you can also create your own custom icons for classes to appear in the editor. For the actual process of creating editor icons to be integrated within the engine, -please refer to :ref:`doc_editor_icons` first. +please refer to `doc_editor_icons` first. Once you've created your icon(s), proceed with the following steps: @@ -557,10 +557,10 @@ Remember to: But this is not all, depending what you do, you will be greeted with some (hopefully positive) surprises. -- If you inherit from :ref:`class_Node` (or any derived node type, such as +- If you inherit from `class_Node` (or any derived node type, such as Sprite), your new class will appear in the editor, in the inheritance tree in the "Add Node" dialog. -- If you inherit from :ref:`class_Resource`, it will appear in the resource +- If you inherit from `class_Resource`, it will appear in the resource list, and all the exposed properties can be serialized when saved/loaded. - By this same logic, you can extend the Editor and almost any area of diff --git a/development/cpp/custom_resource_format_loaders.rst b/development/cpp/custom_resource_format_loaders.rst index 7eba16e..73a8776 100644 --- a/development/cpp/custom_resource_format_loaders.rst +++ b/development/cpp/custom_resource_format_loaders.rst @@ -12,12 +12,12 @@ path again, the previous loaded Resource will be referenced. Naturally, loaded resources must be stateless. This guide assumes the reader knows how to create C++ modules and Godot -data types. If not, refer to this guide :ref:`doc_custom_modules_in_c++`. +data types. If not, refer to this guide `doc_custom_modules_in_c++`. References ~~~~~~~~~~ -- :ref:`ResourceLoader` +- `ResourceLoader` - `core/io/resource_loader.cpp `_ What for? @@ -157,7 +157,7 @@ If you'd like to be able to edit and save a resource, you can implement a Creating custom data types -------------------------- -Godot may not have a proper substitute within its :ref:`doc_core_types` +Godot may not have a proper substitute within its `doc_core_types` or managed resources. Godot needs a new registered data type to understand additional binary formats such as machine learning models. diff --git a/development/cpp/object_class.rst b/development/cpp/object_class.rst index adefb44..ffd26de 100644 --- a/development/cpp/object_class.rst +++ b/development/cpp/object_class.rst @@ -6,12 +6,12 @@ Object class .. seealso:: This page describes the C++ implementation of objects in Godot. - Looking for the Object class reference? :ref:`Have a look here. ` + Looking for the Object class reference? `Have a look here. ` General definition ------------------ -:ref:`Object ` is the base class for almost everything. Most classes in Godot +`Object ` is the base class for almost everything. Most classes in Godot inherit directly or indirectly from it. Objects provide reflection and editable properties, and declaring them is a matter of using a single macro like this. @@ -240,14 +240,14 @@ Adding signals to a class is done in ``_bind_methods``, using the Notifications ------------- -All objects in Godot have a :ref:`_notification ` +All objects in Godot have a `_notification ` method that allows it to respond to engine level callbacks that may relate to it. -More information can be found on the :ref:`doc_godot_notifications` page. +More information can be found on the `doc_godot_notifications` page. References ---------- -:ref:`Reference ` inherits from Object and holds a +`Reference ` inherits from Object and holds a reference count. It is the base for reference counted object types. Declaring them must be done using Ref<> template. For example: @@ -270,7 +270,7 @@ References: Resources: ---------- -:ref:`Resource ` inherits from Reference, so all 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)``. This is normally done by the resource loader though. No two different diff --git a/development/cpp/using_cpp_profilers.rst b/development/cpp/using_cpp_profilers.rst index fb9397c..0f52ecc 100644 --- a/development/cpp/using_cpp_profilers.rst +++ b/development/cpp/using_cpp_profilers.rst @@ -57,7 +57,7 @@ The ``--quit`` option works with ``--editor``, ``--project-manager`` or .. seealso:: - See :ref:`doc_command_line_tutorial` for more command line arguments + See `doc_command_line_tutorial` for more command line arguments supported by Godot. Profiler-specific instructions diff --git a/development/editor/creating_icons.rst b/development/editor/creating_icons.rst index 97e72c6..c1d57d8 100644 --- a/development/editor/creating_icons.rst +++ b/development/editor/creating_icons.rst @@ -86,7 +86,7 @@ make a separate pull request for your icons to be available within the editor as they can be self-contained. For specific instructions on how to create module icons, refer to -:ref:`Creating custom module icons`. +`Creating custom module icons`. Troubleshooting ~~~~~~~~~~~~~~~ diff --git a/development/editor/editor_style_guide.rst b/development/editor/editor_style_guide.rst index 935674a..f46ae4c 100644 --- a/development/editor/editor_style_guide.rst +++ b/development/editor/editor_style_guide.rst @@ -28,7 +28,7 @@ Writing style .. seealso:: - Try to follow the :ref:`doc_docs_writing_guidelines` in addition to the + Try to follow the `doc_docs_writing_guidelines` in addition to the guidelines outlined above. Button and menu texts @@ -52,7 +52,7 @@ contain few items make it difficult to navigate the inspector, while missing the benefits of using sections such as folding. There are some valid exceptions for this, such as material features in -:ref:`class_SpatialMaterial`. +`class_SpatialMaterial`. This advice also applies to the Project Settings and Editor Settings. diff --git a/development/editor/introduction_to_editor_development.rst b/development/editor/introduction_to_editor_development.rst index ed72aab..75b637e 100644 --- a/development/editor/introduction_to_editor_development.rst +++ b/development/editor/introduction_to_editor_development.rst @@ -9,12 +9,12 @@ On this page, you will learn: - How to work efficiently on the Godot editor's C++ code. This guide is aimed at current or future engine contributors. -To create editor plugins in GDScript, see :ref:`doc_making_plugins` instead. +To create editor plugins in GDScript, see `doc_making_plugins` instead. .. seealso:: If you are new to Godot, we recommended you to read - :ref:`doc_godot_design_philosophy` before continuing. Since the Godot editor + `doc_godot_design_philosophy` before continuing. Since the Godot editor is a Godot project written in C++, much of the engine's philosophy applies to the editor. @@ -22,7 +22,7 @@ Technical choices ----------------- The Godot editor is drawn using Godot's renderer and -:ref:`UI system `. It does *not* rely on a toolkit +`UI system `. It does *not* rely on a toolkit such as GTK or Qt. This is similar in spirit to software like Blender. While using toolkits makes it easier to achieve a "native" appearance, they are also quite heavy and their licensing is not compatible with Godot's. @@ -37,7 +37,7 @@ The editor's code is fully self-contained in the of the Godot source repository. Some editor functionality is also implemented via -:ref:`modules `. Some of these are only enabled in +`modules `. Some of these are only enabled in editor builds to decrease the binary size of export templates. See the `modules/ `__ folder in the Godot source repository. @@ -83,6 +83,6 @@ Development tips ---------------- To iterate quickly on the editor, we recommend to set up a test project and -:ref:`open it from the command line ` after compiling +`open it from the command line ` after compiling the editor. This way, you don't have to go through the project manager every time you start Godot. diff --git a/getting_started/first_2d_game/02.player_scene.rst b/getting_started/first_2d_game/02.player_scene.rst index b7d909e..6404c19 100644 --- a/getting_started/first_2d_game/02.player_scene.rst +++ b/getting_started/first_2d_game/02.player_scene.rst @@ -15,7 +15,7 @@ Node structure To begin, we need to choose a root node for the player object. As a general rule, a scene's root node should reflect the object's desired functionality - -what the object *is*. Click the "Other Node" button and add an :ref:`Area2D +what the object *is*. Click the "Other Node" button and add an `Area2D ` node to the scene. .. image:: img/add_node.png @@ -42,21 +42,21 @@ or :kbd:`Cmd + S` on macOS. - **GDScript**: Classes (nodes) use PascalCase, variables and functions use snake_case, and constants use ALL_CAPS (See - :ref:`doc_gdscript_styleguide`). + `doc_gdscript_styleguide`). - **C#**: Classes, export variables and methods use PascalCase, private fields use _camelCase, local variables and parameters use - camelCase (See :ref:`doc_c_sharp_styleguide`). Be careful to type + camelCase (See `doc_c_sharp_styleguide`). Be careful to type the method names precisely when connecting signals. Sprite animation ~~~~~~~~~~~~~~~~ -Click on the ``Player`` node and add an :ref:`AnimatedSprite +Click on the ``Player`` node and add an `AnimatedSprite ` node as a child. The ``AnimatedSprite`` will handle the appearance and animations for our player. Notice that there is a warning symbol -next to the node. An ``AnimatedSprite`` requires a :ref:`SpriteFrames +next to the node. An ``AnimatedSprite`` requires a `SpriteFrames ` resource, which is a list of the animations it can display. To create one, find the ``Frames`` property in the Inspector and click "[empty]" -> "New SpriteFrames". Click again to open the "SpriteFrames" panel: @@ -80,7 +80,7 @@ heading. .. image:: img/player_scale.png -Finally, add a :ref:`CollisionShape2D ` as a child of +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 fit, so next to "Shape" in the Inspector, click "[empty]"" -> "New diff --git a/getting_started/first_2d_game/03.coding_the_player.rst b/getting_started/first_2d_game/03.coding_the_player.rst index 074bc91..34ce9d7 100644 --- a/getting_started/first_2d_game/03.coding_the_player.rst +++ b/getting_started/first_2d_game/03.coding_the_player.rst @@ -21,7 +21,7 @@ click "Create": .. image:: img/attach_node_window.png .. note:: If this is your first time encountering GDScript, please read - :ref:`doc_scripting` before continuing. + `doc_scripting` before continuing. Start by declaring the member variables this object will need: @@ -130,7 +130,7 @@ We can prevent that if we *normalize* the velocity, which means we set its 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 :ref:`doc_vector_math`. + 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 diff --git a/getting_started/first_2d_game/04.creating_the_enemy.rst b/getting_started/first_2d_game/04.creating_the_enemy.rst index 8207c4b..7af1838 100644 --- a/getting_started/first_2d_game/04.creating_the_enemy.rst +++ b/getting_started/first_2d_game/04.creating_the_enemy.rst @@ -15,23 +15,23 @@ Node setup Click Scene -> New Scene and add the following nodes: -- :ref:`RigidBody2D ` (named ``Mob``) +- `RigidBody2D ` (named ``Mob``) - - :ref:`AnimatedSprite ` - - :ref:`CollisionShape2D ` - - :ref:`VisibilityNotifier2D ` + - `AnimatedSprite ` + - `CollisionShape2D ` + - `VisibilityNotifier2D ` Don't forget to set the children so they can't be selected, like you did with the Player scene. -In the :ref:`RigidBody2D ` properties, set ``Gravity Scale`` +In the `RigidBody2D ` properties, set ``Gravity Scale`` to ``0``, so the mob will not fall downward. In addition, under the -:ref:`CollisionObject2D ` section, click the ``Mask`` property and uncheck the first +`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 :ref:`AnimatedSprite ` like you did for the +Set up the `AnimatedSprite ` like you did for the player. This time, we have 3 animations: ``fly``, ``swim``, and ``walk``. There are two images for each animation in the art folder. diff --git a/getting_started/first_2d_game/05.the_main_game_scene.rst b/getting_started/first_2d_game/05.the_main_game_scene.rst index ae12b9f..1680a87 100644 --- a/getting_started/first_2d_game/05.the_main_game_scene.rst +++ b/getting_started/first_2d_game/05.the_main_game_scene.rst @@ -5,7 +5,7 @@ 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 :ref:`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.) @@ -17,13 +17,13 @@ Click the **Instance** button (represented by a chain link icon) and select your Now, add the following nodes as children of ``Main``, and name them as shown (values are in seconds): -- :ref:`Timer ` (named ``MobTimer``) - to control how often mobs +- `Timer ` (named ``MobTimer``) - to control how often mobs spawn -- :ref:`Timer ` (named ``ScoreTimer``) - to increment the score +- `Timer ` (named ``ScoreTimer``) - to increment the score every second -- :ref:`Timer ` (named ``StartTimer``) - to give a delay before +- `Timer ` (named ``StartTimer``) - to give a delay before starting -- :ref:`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: @@ -39,7 +39,7 @@ 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 :ref:`Path2D ` node +location on the edge of the screen. Add a `Path2D ` node named ``MobPath`` as a child of ``Main``. When you select ``Path2D``, you will see some new buttons at the top of the editor: @@ -61,7 +61,7 @@ intersecting lines, respectively. 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 :ref:`PathFollow2D ` +Now that the path is defined, add a `PathFollow2D ` 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. diff --git a/getting_started/first_2d_game/06.heads_up_display.rst b/getting_started/first_2d_game/06.heads_up_display.rst index ca9d598..32dd2ab 100644 --- a/getting_started/first_2d_game/06.heads_up_display.rst +++ b/getting_started/first_2d_game/06.heads_up_display.rst @@ -6,11 +6,11 @@ Heads up display 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 :ref:`CanvasLayer ` node named +Create a new scene, and add a `CanvasLayer ` node named ``HUD``. "HUD" stands for "heads-up display", an informational display that appears as an overlay on top of the game view. -The :ref:`CanvasLayer ` node lets us draw our UI elements on +The `CanvasLayer ` node lets us draw our UI elements on a layer above the rest of the game, so that the information it displays isn't covered up by any game elements like the player or mobs. @@ -20,16 +20,16 @@ The HUD needs to display the following information: - A message, such as "Game Over" or "Get Ready!" - A "Start" button to begin the game. -The basic node for UI elements is :ref:`Control `. To create our -UI, we'll use two types of :ref:`Control ` nodes: :ref:`Label -` and :ref:`Button `. +The basic node for UI elements is `Control `. To create our +UI, we'll use two types of `Control ` nodes: `Label +` and `Button `. Create the following as children of the ``HUD`` node: -- :ref:`Label ` named ``ScoreLabel``. -- :ref:`Label ` named ``Message``. -- :ref:`Button ` named ``StartButton``. -- :ref:`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 diff --git a/getting_started/first_2d_game/07.finishing-up.rst b/getting_started/first_2d_game/07.finishing-up.rst index e85c1b7..9a035cd 100644 --- a/getting_started/first_2d_game/07.finishing-up.rst +++ b/getting_started/first_2d_game/07.finishing-up.rst @@ -12,7 +12,7 @@ Background ~~~~~~~~~~ The default gray background is not very appealing, so let's change its color. -One way to do this is to use a :ref:`ColorRect ` node. Make it +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 select "Layout" -> "Full Rect" so that it covers the screen. @@ -28,7 +28,7 @@ experience. In your game assets folder, you have two sound files: "House In a Forest Loop.ogg" for background music, and "gameover.wav" for when the player loses. -Add two :ref:`AudioStreamPlayer ` nodes as children of +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 audio file. @@ -75,5 +75,5 @@ interface, sounds, and more. Congratulations! There's still much to learn, but you can take a moment to appreciate what you achieved. -And when you're ready, you can move on to :ref:`doc_your_first_3d_game` to learn +And when you're ready, you can move on to `doc_your_first_3d_game` to learn to create a complete 3D game from scratch, in Godot. diff --git a/getting_started/first_2d_game/index.rst b/getting_started/first_2d_game/index.rst index 9d3e4c6..ff9d9a6 100644 --- a/getting_started/first_2d_game/index.rst +++ b/getting_started/first_2d_game/index.rst @@ -14,7 +14,7 @@ a 2D game. .. note:: This project is an introduction to the Godot engine. It assumes that you have some programming experience already. If you're new to - programming entirely, you should start here: :ref:`doc_scripting`. + programming entirely, you should start here: `doc_scripting`. The game is called "Dodge the Creeps!". Your character must move and avoid the enemies for as long as possible. @@ -45,7 +45,7 @@ Prerequisites ------------- This step-by-step tutorial is intended for beginners who followed the complete -:ref:`Getting Started `. +`Getting Started `. If you're an experienced programmer, you can find the complete demo's source code here: `Godot demo projects diff --git a/getting_started/first_3d_game/02.player_input.rst b/getting_started/first_3d_game/02.player_input.rst index eb8b16d..42d1162 100644 --- a/getting_started/first_3d_game/02.player_input.rst +++ b/getting_started/first_3d_game/02.player_input.rst @@ -24,7 +24,7 @@ the jump and squash mechanics. .. seealso:: To learn more about the different physics node types, see the - :ref:`doc_physics_introduction`. + `doc_physics_introduction`. 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. diff --git a/getting_started/first_3d_game/03.player_movement_code.rst b/getting_started/first_3d_game/03.player_movement_code.rst index cd950be..484ffcc 100644 --- a/getting_started/first_3d_game/03.player_movement_code.rst +++ b/getting_started/first_3d_game/03.player_movement_code.rst @@ -71,7 +71,7 @@ kinematic or rigid body. .. seealso:: To learn more about the difference between ``_process()`` and - ``_physics_process()``, see :ref:`doc_idle_and_physics_processing`. + ``_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 diff --git a/getting_started/first_3d_game/04.mob_scene.rst b/getting_started/first_3d_game/04.mob_scene.rst index 8fecbbe..e91b0c7 100644 --- a/getting_started/first_3d_game/04.mob_scene.rst +++ b/getting_started/first_3d_game/04.mob_scene.rst @@ -69,7 +69,7 @@ Godot has a node that detects when objects leave the screen, reason to use pools is to avoid freezes with garbage-collected languages like C# or Lua. GDScript uses a different technique to manage memory, reference counting, which doesn't have that caveat. You can learn more - about that here :ref:`doc_gdscript_basics_memory_management`. + about that here `doc_gdscript_basics_memory_management`. Select the *Mob* node and add a *VisibilityNotifier* as a child of it. Another box, pink this time, appears. When this box completely leaves the screen, the @@ -124,7 +124,7 @@ You may see a warning in GDScript that the return value from 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 -system, see :ref:`doc_gdscript_warning_system`. +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 diff --git a/getting_started/first_3d_game/06.jump_and_squash.rst b/getting_started/first_3d_game/06.jump_and_squash.rst index 5cb5fda..7abee6c 100644 --- a/getting_started/first_3d_game/06.jump_and_squash.rst +++ b/getting_started/first_3d_game/06.jump_and_squash.rst @@ -7,7 +7,7 @@ In this part, we'll add the ability to jump, to squash the monsters. In the next lesson, we'll make the player die when a monster hits them on the ground. First, we have to change a few settings related to physics interactions. Enter -the world of :ref:`physics layers +the world of `physics layers `. Controlling physics interactions @@ -155,7 +155,7 @@ Let's add the squash mechanic next. We're going to make the character bounce over monsters and kill them at the same time. 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 :ref:`group +collisions with the floor. To do so, we can use Godot's `group ` tagging feature. Open the scene ``Mob.tscn`` again and select the *Mob* node. Go to the *Node* @@ -224,18 +224,18 @@ 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 :ref:`KinematicBody` class and are related to +the `KinematicBody` class and are related to ``move_and_slide()``. ``get_slide_collision()`` returns a -:ref:`KinematicCollision` object that holds +`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")``. .. note:: - The method ``is_in_group()`` is available on every :ref:`Node`. + The method ``is_in_group()`` is available on every `Node`. To check that we are landing on the monster, we use the vector dot product: ``Vector3.UP.dot(collision.normal) > 0.1``. The collision normal is a 3D vector diff --git a/getting_started/first_3d_game/08.score_and_replay.rst b/getting_started/first_3d_game/08.score_and_replay.rst index f17e6f5..a8037dc 100644 --- a/getting_started/first_3d_game/08.score_and_replay.rst +++ b/getting_started/first_3d_game/08.score_and_replay.rst @@ -61,7 +61,7 @@ By default, a theme only has one property, the *Default Font*. You can add more properties to the theme resource to design complex user interfaces, but that is beyond the scope of this series. To learn more about - creating and editing themes, see :ref:`doc_gui_skinning`. + creating and editing themes, see `doc_gui_skinning`. Click the *Default Font* property and create a new *DynamicFont*. @@ -153,7 +153,7 @@ function. .. seealso:: - You can learn more about string formatting here: :ref:`doc_gdscript_printf`. + You can learn more about string formatting here: `doc_gdscript_printf`. You can now play the game and squash a few enemies to see the score increase. @@ -261,7 +261,7 @@ gdscript GDScript get_tree().reload_current_scene() ``` -The function ``get_tree()`` gives us access to the global :ref:`SceneTree +The function ``get_tree()`` gives us access to the global `SceneTree ` object, which allows us to reload and restart the current scene. @@ -269,7 +269,7 @@ Adding music ------------ To add music that plays continuously in the background, we're going to use -another feature in Godot: :ref:`autoloads `. +another feature in Godot: `autoloads `. To play audio, all you need to do is add an *AudioStreamPlayer* node to your scene and attach an audio file to it. When you start the scene, it can play diff --git a/getting_started/first_3d_game/going_further.rst b/getting_started/first_3d_game/going_further.rst index 90ac861..d171460 100644 --- a/getting_started/first_3d_game/going_further.rst +++ b/getting_started/first_3d_game/going_further.rst @@ -29,11 +29,11 @@ information about 2D, 3D, physics, rendering and performance, and much more. Here are the sections we recommend you to explore next: -1. Read the :ref:`Scripting section ` to learn essential programming features you’ll use +1. Read the `Scripting section ` to learn essential programming features you’ll use in every project. -2. The :ref:`3D ` and :ref:`Physics ` sections will teach you more about 3D game creation in the +2. The `3D ` and `Physics ` sections will teach you more about 3D game creation in the engine. -3. :ref:`Inputs ` is another important one for any game project. +3. `Inputs ` is another important one for any game project. You can start with these or, if you prefer, look at the sidebar menu on the left and pick your options. diff --git a/getting_started/first_3d_game/index.rst b/getting_started/first_3d_game/index.rst index a2d23cb..bf7d5bc 100644 --- a/getting_started/first_3d_game/index.rst +++ b/getting_started/first_3d_game/index.rst @@ -9,7 +9,7 @@ project of your own like the animated gif below. |image0| -The game we'll code here is similar to :ref:`doc_your_first_2d_game`, with a twist: +The game we'll code here is similar to `doc_your_first_2d_game`, with a twist: you can now jump and your goal is to squash the creeps. This way, you will both **recognize patterns** you learned in the previous tutorial and **build upon them** with new code and features. diff --git a/getting_started/introduction/first_look_at_the_editor.rst b/getting_started/introduction/first_look_at_the_editor.rst index 829483d..4d2c54b 100644 --- a/getting_started/introduction/first_look_at_the_editor.rst +++ b/getting_started/introduction/first_look_at_the_editor.rst @@ -13,7 +13,7 @@ This page will give you a brief overview of Godot's interface. We're going to look at the different main screens and docks to help you situate yourself. .. seealso:: For a comprehensive breakdown of the editor's interface and how to - use it, see the :ref:`Editor manual `. + use it, see the `Editor manual `. The Project manager ------------------- @@ -109,7 +109,7 @@ options related to the 3D view. .. image:: img/editor_intro_3d_viewport_perspective.png -.. note:: Read :ref:`doc_introduction_to_3d` for more detail about the **3D +.. note:: Read `doc_introduction_to_3d` for more detail about the **3D main screen**. The **Script screen** is a complete code editor with a debugger, rich @@ -123,7 +123,7 @@ and assets to use in your projects. .. image:: img/editor_intro_workspace_assetlib.png .. seealso:: You can learn more about the asset library in - :ref:`doc_what_is_assetlib`. + `doc_what_is_assetlib`. Integrated class reference -------------------------- diff --git a/getting_started/introduction/godot_design_philosophy.rst b/getting_started/introduction/godot_design_philosophy.rst index 218361d..50c83be 100644 --- a/getting_started/introduction/godot_design_philosophy.rst +++ b/getting_started/introduction/godot_design_philosophy.rst @@ -116,7 +116,7 @@ manage states and transitions visually.* Future Godot 4.x releases may have VisualScript reimplemented as an extension. While Godot 3.x will keep VisualScript supported, we recommend - :ref:`trying out GDScript ` instead, + `trying out GDScript ` instead, especially if you intend to migrate your project to Godot 4. Open source diff --git a/getting_started/introduction/introduction_to_godot.rst b/getting_started/introduction/introduction_to_godot.rst index c149dc9..e741d1c 100644 --- a/getting_started/introduction/introduction_to_godot.rst +++ b/getting_started/introduction/introduction_to_godot.rst @@ -24,7 +24,7 @@ programming skills or a developer to port the game for you. .. note:: The Godot team can't provide an open-source console export due to the licensing terms imposed by console manufacturers. Regardless of the engine you use, though, releasing games on consoles is always a lot of - work. You can read more on that here: :ref:`doc_consoles`. + work. You can read more on that here: `doc_consoles`. What can the engine do? ----------------------- @@ -71,15 +71,15 @@ Programming languages Let's talk about the available programming languages. -You can code your games using :ref:`GDScript `, a +You can code your games using `GDScript `, a Godot-specific and tightly integrated language with a lightweight syntax, or -:ref:`C# `, which is popular in the games industry. +`C# `, which is popular in the games industry. These are the two main scripting languages we support. Godot also supports a node-based visual programming language named -:ref:`VisualScript `. +`VisualScript `. -With the :ref:`GDNative ` technology, you can also write +With the `GDNative ` technology, you can also write gameplay or high-performance algorithms in C or C++ without recompiling the engine. You can use this technology to integrate third-party libraries and other Software Development Kits (SDK) in the engine. @@ -89,7 +89,7 @@ completely free and open-source. .. seealso:: These are the five officially supported programming languages. The community maintains support for many more. For more information, - see :ref:`GDNative third-party bindings + see `GDNative third-party bindings `. What do I need to know to use Godot? @@ -113,7 +113,7 @@ countless hours and hurdles learning any game engine afterward. skills you learn with one language transfer well to others. We will provide you with more Godot-specific learning resources in -:ref:`doc_learning_new_features`. +`doc_learning_new_features`. In the next part, you will get an overview of the engine's essential concepts. diff --git a/getting_started/introduction/learning_new_features.rst b/getting_started/introduction/learning_new_features.rst index 41ab241..ba79b2e 100644 --- a/getting_started/introduction/learning_new_features.rst +++ b/getting_started/introduction/learning_new_features.rst @@ -33,7 +33,7 @@ from within the Godot editor. To do so, go to Help -> Search or press .. image:: img/manual_class_reference_search.png -To browse it online, head to the manual's :ref:`Class Reference ` +To browse it online, head to the manual's `Class Reference ` section. A class reference's page tells you: @@ -148,4 +148,4 @@ This manual aims to provide a comprehensive reference of Godot's features. Aside from the 2D and 3D getting started series, it does not contain tutorials to implement specific game genres. If you're looking for a tutorial about creating a role-playing game, a platformer, or other, please see -:ref:`doc_community_tutorials`, which lists content made by the Godot community. +`doc_community_tutorials`, which lists content made by the Godot community. diff --git a/getting_started/step_by_step/index.rst b/getting_started/step_by_step/index.rst index 1a43ccf..760e857 100644 --- a/getting_started/step_by_step/index.rst +++ b/getting_started/step_by_step/index.rst @@ -1,12 +1,12 @@ Step by step ============ -This series builds upon the :ref:`Introduction to Godot +This series builds upon the `Introduction to Godot ` and will get you started with the editor and the engine. You will learn more about nodes and scenes, code your first classes with GDScript, use signals to make nodes communicate with one another, and more. -The following lessons are here to prepare you for :ref:`doc_your_first_2d_game`, a +The following lessons are here to prepare you for `doc_your_first_2d_game`, a step-by-step tutorial where you will code a game from scratch. By the end of it, you will have the necessary foundations to explore more features in other sections. We also included links to pages that cover a given topic in-depth diff --git a/getting_started/step_by_step/instancing.rst b/getting_started/step_by_step/instancing.rst index 65a955c..237eca7 100644 --- a/getting_started/step_by_step/instancing.rst +++ b/getting_started/step_by_step/instancing.rst @@ -13,10 +13,10 @@ You can create as many scenes as you'd like and save them as files with the the previous lesson was an example. We call those files "Packed Scenes" as they pack information about your scene's content. -Here's an example of a ball. It's composed of a :ref:`RigidBody2D +Here's an example of a ball. It's composed of a `RigidBody2D ` node as its root named Ball, which allows the ball to fall -and bounce on walls, a :ref:`Sprite ` node, and a -:ref:`CollisionShape2D `. +and bounce on walls, a `Sprite ` node, and a +`CollisionShape2D `. .. image:: img/instancing_ball_scene.png diff --git a/getting_started/step_by_step/nodes_and_scenes.rst b/getting_started/step_by_step/nodes_and_scenes.rst index c5ba205..6ba9026 100644 --- a/getting_started/step_by_step/nodes_and_scenes.rst +++ b/getting_started/step_by_step/nodes_and_scenes.rst @@ -5,7 +5,7 @@ Nodes and Scenes ================ -In :ref:`doc_key_concepts_overview`, we saw that a Godot game is a tree of +In `doc_key_concepts_overview`, we saw that a Godot game is a tree of scenes and that each scene is a tree of nodes. In this lesson, we explain a bit more about them. You will also create your first scene. @@ -147,7 +147,7 @@ button to save it as "Label.tscn". 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 :ref:`doc_filesystem`. + Godot, see `doc_filesystem`. The application should open in a new window and display the text "Hello World". diff --git a/getting_started/step_by_step/scripting_first_script.rst b/getting_started/step_by_step/scripting_first_script.rst index 3243e22..bf4baa3 100644 --- a/getting_started/step_by_step/scripting_first_script.rst +++ b/getting_started/step_by_step/scripting_first_script.rst @@ -19,16 +19,16 @@ Creating your first script ========================== In this lesson, you will code your first script to make the Godot icon turn in -circles using GDScript. As we mentioned :ref:`in the introduction +circles using GDScript. As we mentioned `in the introduction `, we assume you have programming foundations. The equivalent C# code has been included in another tab for convenience. .. image:: img/scripting_first_script_rotating_godot.gif .. seealso:: To learn more about GDScript, its keywords, and its syntax, head to - the :ref:`GDScript reference`. + the `GDScript reference`. -.. seealso:: To learn more about C#, head to the :ref:`C# basics ` page. +.. seealso:: To learn more about C#, head to the `C# basics ` page. Project setup ------------- @@ -102,7 +102,7 @@ node, including classes it extends, like ``Node2D``, ``CanvasItem``, and ``Node``. .. note:: In GDScript, if you omit the line with the ``extends`` keyword, your - class will implicitly extend :ref:`Reference `, which + 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 @@ -253,7 +253,7 @@ 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 -itself is of type :ref:`Vector2 `, a built-in type in Godot +itself is of type `Vector2 `, a built-in type in Godot representing a 2D vector. Run the scene to see the Godot head run in circles. @@ -261,11 +261,11 @@ Run the scene to see the Godot head run in circles. .. image:: img/scripting_first_script_rotating_godot.gif .. note:: Moving a node like that does not take into account colliding with - walls or the floor. In :ref:`doc_your_first_2d_game`, you will learn + walls or the floor. In `doc_your_first_2d_game`, you will learn another approach to moving objects while detecting collisions. Our node currently moves by itself. In the next part -:ref:`doc_scripting_player_input`, we'll use player input to control it. +`doc_scripting_player_input`, we'll use player input to control it. Complete script --------------- diff --git a/getting_started/step_by_step/scripting_languages.rst b/getting_started/step_by_step/scripting_languages.rst index 2cb636f..9377653 100644 --- a/getting_started/step_by_step/scripting_languages.rst +++ b/getting_started/step_by_step/scripting_languages.rst @@ -25,7 +25,7 @@ Available scripting languages Godot offers **five gameplay programming languages**: GDScript, C#, VisualScript, and, via its GDNative technology, C and C++. There are more -:ref:`community-supported languages `, +`community-supported languages `, but these are the official ones. You can use multiple languages in a single project. For instance, in a team, you @@ -44,7 +44,7 @@ developers. Future Godot 4.x releases may have VisualScript reimplemented as an extension. While Godot 3.x will keep VisualScript supported, we recommend - :ref:`trying out GDScript ` instead, + `trying out GDScript ` instead, especially if you intend to migrate your project to Godot 4. Which language should I use? @@ -68,7 +68,7 @@ Let's look at each language's features, as well as its pros and cons. GDScript ~~~~~~~~ -:ref:`GDScript` is an +`GDScript` is an `object-oriented `_ and `imperative `_ programming language built for Godot. It's made by and for game developers @@ -146,10 +146,10 @@ VisualScript Future Godot 4.x releases may have VisualScript reimplemented as an extension. While Godot 3.x will keep VisualScript supported, we recommend - :ref:`trying out GDScript ` instead, + `trying out GDScript ` instead, especially if you intend to migrate your project to Godot 4. -:ref:`Visual Scripting` is a graph-based visual +`Visual Scripting` is a graph-based visual programming language where you connect blocks. It can be a great tool for non-programmers like game designers and artists. @@ -166,7 +166,7 @@ is slow compared to using other programming languages. .. seealso:: For more information, see - :ref:`Getting started with VisualScript `. + `Getting started with VisualScript `. C and C++ via GDNative ~~~~~~~~~~~~~~~~~~~~~~ diff --git a/getting_started/step_by_step/scripting_player_input.rst b/getting_started/step_by_step/scripting_player_input.rst index 2f4fa3a..ecd35b8 100644 --- a/getting_started/step_by_step/scripting_player_input.rst +++ b/getting_started/step_by_step/scripting_player_input.rst @@ -7,7 +7,7 @@ Listening to player input ========================= -Building upon the previous lesson :ref:`doc_scripting_first_script`, let's look +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. @@ -19,7 +19,7 @@ You have two main tools to process the player's input in Godot: ``_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 :ref:`doc_inputevent`. + more about input callbacks, see `doc_inputevent`. 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. @@ -144,5 +144,5 @@ 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. -In the next lesson :ref:`doc_signals`, we'll build upon the relationship between +In the next lesson `doc_signals`, we'll build upon the relationship between scripts and nodes by having our nodes trigger code in scripts. diff --git a/getting_started/step_by_step/signals.rst b/getting_started/step_by_step/signals.rst index 87e15ae..54f59c2 100644 --- a/getting_started/step_by_step/signals.rst +++ b/getting_started/step_by_step/signals.rst @@ -30,7 +30,7 @@ the bar to reflect the change. To do so, in Godot, you would use signals. https://gameprogrammingpatterns.com/observer.html We will now use a signal to make our Godot icon from the previous lesson -(:ref:`doc_scripting_player_input`) move and stop by pressing a button. +(`doc_scripting_player_input`) move and stop by pressing a button. .. Example @@ -141,7 +141,7 @@ 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 -method to toggle processing on and off: :ref:`Node.set_process() +method to toggle processing on and off: `Node.set_process() `. Another method of the Node class, ``is_processing()``, returns ``true`` if idle processing is active. We can use the ``not`` keyword to invert the value. @@ -198,7 +198,7 @@ Connecting a signal via code You can connect signals via code instead of using the editor. This is necessary when you create nodes or instantiate scenes inside of a script. -Let's use a different node here. Godot has a :ref:`Timer ` node +Let's use a different node here. Godot has a `Timer ` node that's useful to implement skill cooldown times, weapon reloading, and more. Head back to the 2D workspace. You can either click the "2D" text at the top of @@ -229,11 +229,11 @@ We need to do two operations to connect the nodes via code: listen to the Timer's "timeout" signal. We want to connect the signal when the scene is instantiated, and we can do that -using the :ref:`Node._ready() ` built-in function, +using the `Node._ready() ` built-in function, which is called automatically by the engine when a node is fully instantiated. To get a reference to a node relative to the current one, we use the method -:ref:`Node.get_node() `. We can store the reference +`Node.get_node() `. We can store the reference in a variable. gdscript GDScript @@ -393,9 +393,9 @@ Signals have many uses. With them, you can react to a node entering or exiting 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 :ref:`Area2D ` representing a coin emits a +For example, an `Area2D ` representing a coin emits a ``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, :ref:`doc_your_first_2d_game`, you'll create a complete 2D +In the next section, `doc_your_first_2d_game`, you'll create a complete 2D game and put everything you learned so far into practice. diff --git a/index.rst b/index.rst index d293e91..36cfb14 100644 --- a/index.rst +++ b/index.rst @@ -31,7 +31,7 @@ Godot Docs – *3.5* branch Welcome to the official documentation of `Godot Engine `__, the free and open source community-driven 2D and 3D game engine! If you are new to this documentation, we recommend that you read the -:ref:`introduction page ` to get an overview of what this +`introduction page ` to get an overview of what this documentation has to offer. The table of contents below and in the sidebar should let you easily access the @@ -132,6 +132,6 @@ The main documentation for the site is organized into the following sections: .. Indices and tables .. ------------------ .. -.. * :ref:`genindex` -.. * :ref:`modindex` -.. * :ref:`search` +.. * `genindex` +.. * `modindex` +.. * `search` diff --git a/tutorials/2d/2d_lights_and_shadows.rst b/tutorials/2d/2d_lights_and_shadows.rst index e44927c..21dabcb 100644 --- a/tutorials/2d/2d_lights_and_shadows.rst +++ b/tutorials/2d/2d_lights_and_shadows.rst @@ -46,33 +46,33 @@ Nodes ----- The demo uses four different nodes: - * :ref:`CanvasModulate ` - * :ref:`Sprite ` - * :ref:`Light2D ` - * :ref:`LightOccluder2D ` + * `CanvasModulate ` + * `Sprite ` + * `Light2D ` + * `LightOccluder2D ` -:ref:`CanvasModulate` is used to darken the scene. +`CanvasModulate` is used to darken the scene. -:ref:`Sprites ` are used to display the textures for the light blobs, the +`Sprites ` are used to display the textures for the light blobs, the background, and for the shadow casters. -:ref:`Light2Ds ` are used to light the scene. The way a light typically works +`Light2Ds ` are used to light the scene. The way a light typically works is by adding a selected texture over the rest of the scene to simulate lighting. But it can be used in other ways, for example masking out parts of the scene. -:ref:`LightOccluder2Ds ` are used to tell the shader which parts of -the scene cast shadows. The shadows appear only on areas covered by the :ref:`Light2D ` and -their direction is based on the center of the :ref:`Light `. +`LightOccluder2Ds ` are used to tell the shader which parts of +the scene cast shadows. The shadows appear only on areas covered by the `Light2D ` and +their direction is based on the center of the `Light `. Lights ------ -:ref:`Lights ` cover the entire extent of their respective Texture. They use additive +`Lights ` cover the entire extent of their respective Texture. They use additive blending to add the color of their texture to the scene. .. image:: img/light_shadow_light.png -:ref:`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. @@ -84,24 +84,24 @@ 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 the color of the light. -For the demo the lights have two components, the :ref:`Light ` itself (which -is the effect of the light), and a :ref:`Sprite ` blob which is an image showing the -location of the light source. A child :ref:`Sprite ` is not necessary to make a -:ref:`Light ` work. +For the demo the lights have two components, the `Light ` itself (which +is the effect of the light), and a `Sprite ` blob which is an image showing the +location of the light source. A child `Sprite ` is not necessary to make a +`Light ` work. .. image:: img/light_shadow_light_blob.png Shadows ------- -Shadows are made by intersecting a :ref:`Light ` with a :ref:`LightOccluder2D `. +Shadows are made by intersecting a `Light ` with a `LightOccluder2D `. -By default shadows are turned off. To turn them on click on the :ref:`Light ` +By default shadows are turned off. To turn them on click on the `Light ` and under the Shadows section check ``Enabled``. -In the demo we are using a :ref:`Sprite ` with a Texture on it to make the "Shadow Casters", -but in reality all you need is a couple of :ref:`LightOccluder2Ds `. By itself -the :ref:`LightOccluder2D ` looks like a dark spot and in this demo the :ref:`Sprite ` is +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 +the `LightOccluder2D ` looks like a dark spot and in this demo the `Sprite ` is just a black square. Step by step @@ -110,54 +110,54 @@ Step by step Now that we have covered the basics of the nodes being used, we can now walk step by step through the process of making a scene like the one found in the demo. -First add a :ref:`Sprite ` and set its texture to the `background image `_. For your game this can be any +First add a `Sprite ` and set its texture to the `background image `_. For your game this can be any background you choose. For this style of shadow it is most likely to be a floor texture. .. image:: img/light_shadow_background.png -Next create three :ref:`Light2D's ` and set their textures to the `light image `_. You can alter their +Next create three `Light2D's ` and set their textures to the `light image `_. You can alter their 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 -Next add a child :ref:`Sprite ` to each of the :ref:`Light ` nodes, and set -the :ref:`Sprite's ` texture to the `blob image `_. Each of these -should stay centered on the :ref:`Light ` node. The blob is the image of the light -itself while the :ref:`Light ` shows the effect that the light has on the scene. The -:ref:`LightOccluder2D's ` will treat the position of the light as the center of the :ref:`Light ` -node, which is why we want the blob to be centered on its parent :ref:`Light `. +Next add a child `Sprite ` to each of the `Light ` nodes, and set +the `Sprite's ` texture to the `blob image `_. Each of these +should stay centered on the `Light ` node. The blob is the image of the light +itself while the `Light ` shows the effect that the light has on the scene. The +`LightOccluder2D's ` will treat the position of the light as the center of the `Light ` +node, which is why we want the blob to be centered on its parent `Light `. .. image:: img/light_shadow_all_lights.png -.. note:: The animations in the demo will not be covered here. See :ref:`doc_introduction_animation` +.. note:: The animations in the demo will not be covered here. See `doc_introduction_animation` for information on creating animations. Right now the scene should look too bright. This is because all three lights are adding color to the scene. -This is why the demo uses a :ref:`CanvasModulate ` in the scene. The -:ref:`CanvasModulate ` multiples the entire viewport by a specific color. +This is why the demo uses a `CanvasModulate ` in the scene. The +`CanvasModulate ` multiples the entire viewport by a specific color. -Add a :ref:`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 Now we add the shadow casters. -The demo uses a :ref:`Node ` named "casters" to organize the shadow casters. Add a -:ref:`Node2D ` to the scene. It will be used to group all the shadow casters together. +The demo uses a `Node ` named "casters" to organize the shadow casters. Add a +`Node2D ` to the scene. It will be used to group all the shadow casters together. This way we can show and hide them all at the same time. -Each shadow caster is made of a :ref:`Sprite `, with a :ref:`LightOccluder2D ` -child. For the demo the :ref:`Sprite ` has a texture -set to the `caster image `_ and nothing else. The child :ref:`LightOccluder2D ` is where all the magic happens. In a -game the :ref:`Sprite ` could be more than a black box; it could be an image of whatever object is casting +Each shadow caster is made of a `Sprite `, with a `LightOccluder2D ` +child. For the demo the `Sprite ` has a texture +set to the `caster image `_ and nothing else. The child `LightOccluder2D ` is where all the magic happens. In a +game the `Sprite ` could be more than a black box; it could be an image of whatever object is casting the shadow: a wall, a magical chest, or anything else. .. image:: img/light_shadow_sprites.png -:ref:`LightOccluder2Ds ` tell the game what shape the occluder has. They hold -an :ref:`OccluderPolygon2D `, which is a container +`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. @@ -169,8 +169,8 @@ will cast a shadow no matter which side the light is on. The other two settings ``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 :ref:`LightOccluder2D ` with ``Closed`` -set to ``off`` in the corresponding :ref:`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 @@ -187,8 +187,8 @@ lines of the polygon can be seen: 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 :ref:`LightOccluder2Ds ` the shadows still won't -appear. You need to go back into the :ref:`Light2Ds ` and under the Shadow +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. .. image:: img/light_shadow_filter0_pcf0.png @@ -219,7 +219,7 @@ forming between the samples. .. note:: ``filter smooth`` is set to ``30``. -The different :ref:`Light ` nodes in the demo use different values for filter smooth. +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 diff --git a/tutorials/2d/2d_meshes.rst b/tutorials/2d/2d_meshes.rst index e7680e8..cc2b580 100644 --- a/tutorials/2d/2d_meshes.rst +++ b/tutorials/2d/2d_meshes.rst @@ -10,7 +10,7 @@ In 3D, meshes are used to display the world. In 2D, they are rare as images are Godot's 2D engine is a pure two-dimensional engine, so it can't really display 3D meshes directly (although it can be done via ``Viewport`` and ``ViewportTexture``). -.. seealso:: If you are interested in displaying 3D meshes on a 2D viewport, see the :ref:`doc_viewport_as_texture` tutorial. +.. 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. diff --git a/tutorials/2d/2d_movement.rst b/tutorials/2d/2d_movement.rst index 3426192..fd2640c 100644 --- a/tutorials/2d/2d_movement.rst +++ b/tutorials/2d/2d_movement.rst @@ -10,7 +10,7 @@ Every beginner has been there: "How do I move my character?" Depending on the style of game you're making, you may have special requirements, but in general the movement in most 2D games is based on a small number of designs. -We'll use :ref:`KinematicBody2D ` for these examples, +We'll use `KinematicBody2D ` for these examples, but the principles will apply to other node types (Area2D, RigidBody2D) as well. .. _doc_2d_movement_setup: @@ -23,7 +23,7 @@ children: ``Sprite`` and ``CollisionShape2D``. You can use the Godot icon ("icon 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 -input actions (see :ref:`InputEvent ` for details): +input actions (see `InputEvent ` for details): .. image:: img/movement_inputs.png @@ -73,13 +73,13 @@ We can prevent that if we *normalize* the velocity, which means we set 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 :ref:`doc_vector_math`. + you can see an explanation of vector usage in Godot at `doc_vector_math`. .. note:: If the code above does nothing when you press the keys, double-check that you've set up input actions correctly as described in the - :ref:`doc_2d_movement_setup` part of this tutorial. + `doc_2d_movement_setup` part of this tutorial. Rotation + movement ------------------- @@ -159,7 +159,7 @@ gdscript GDScript velocity = move_and_slide(velocity) ``` -Here we're using the :ref:`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: diff --git a/tutorials/2d/2d_sprite_animation.rst b/tutorials/2d/2d_sprite_animation.rst index 8ad939b..e6047d4 100644 --- a/tutorials/2d/2d_sprite_animation.rst +++ b/tutorials/2d/2d_sprite_animation.rst @@ -11,10 +11,10 @@ characters with the AnimatedSprite class and the AnimationPlayer. Typically, whe will come in one of two ways: as individual images or as a single sprite sheet containing all the animation's frames. Both can be animated in Godot with the AnimatedSprite class. -First, we'll use :ref:`AnimatedSprite ` to +First, we'll use `AnimatedSprite ` to animate a collection of individual images. Then we will animate a sprite sheet using this class. Finally, we will learn another way to animate a sprite sheet -with :ref:`AnimationPlayer ` and the *Animation* -property of :ref:`Sprite `. +with `AnimationPlayer ` and the *Animation* +property of `Sprite `. .. note:: Art for the following examples by https://opengameart.org/users/ansimuz and by https://opengameart.org/users/tgfcoder @@ -36,11 +36,11 @@ with the following nodes: .. image:: img/2d_animation_tree1.png -.. note:: The root node could also be :ref:`Area2D ` or - :ref:`RigidBody2D `. The animation will still be +.. note:: The root node could also be `Area2D ` or + `RigidBody2D `. The animation will still be made in the same way. Once the animation is completed, you can assign a shape to the CollisionShape2D. See - :ref:`Physics Introduction ` for more + `Physics Introduction ` for more information. Now select the ``AnimatedSprite`` and in its *SpriteFrames* property, select @@ -128,8 +128,8 @@ Sprite sheet with AnimationPlayer --------------------------------- Another way that you can animate when using a sprite sheet is to use a standard -:ref:`Sprite ` node to display the texture, and then animating the -change from texture to texture with :ref:`AnimationPlayer `. +`Sprite ` node to display the texture, and then animating the +change from texture to texture with `AnimationPlayer `. Consider this sprite sheet, which contains 6 frames of animation: @@ -143,11 +143,11 @@ setting up your scene tree: .. image:: img/2d_animation_tree2.png -.. note:: The root node could also be :ref:`Area2D ` or - :ref:`RigidBody2D `. The animation will still be +.. note:: The root node could also be `Area2D ` or + `RigidBody2D `. The animation will still be made in the same way. Once the animation is completed, you can assign a shape to the CollisionShape2D. See - :ref:`Physics Introduction ` for more + `Physics Introduction ` for more information. Drag the spritesheet into the Sprite's *Texture* property, and you'll see the @@ -208,7 +208,7 @@ gdscript GDScript (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. - Instead, it's applied the next time the :ref:`AnimationPlayer ` is processed. + 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)`` diff --git a/tutorials/2d/2d_transforms.rst b/tutorials/2d/2d_transforms.rst index fe94660..d199b0e 100644 --- a/tutorials/2d/2d_transforms.rst +++ b/tutorials/2d/2d_transforms.rst @@ -13,21 +13,21 @@ the screen. This overview discusses very low level details of the engine. Canvas transform ---------------- -As mentioned in the previous tutorial, :ref:`doc_canvas_layers`, every +As mentioned in the previous tutorial, `doc_canvas_layers`, every CanvasItem node (remember that Node2D and Control based nodes use CanvasItem as their common root) will reside in a *Canvas Layer*. Every canvas layer has a transform (translation, rotation, scale, etc.) that -can be accessed as a :ref:`Transform2D `. +can be accessed as a `Transform2D `. Also covered in the previous tutorial, nodes are drawn by default in Layer 0, -in the built-in canvas. To put nodes in a different layer, a :ref:`CanvasLayer +in the built-in canvas. To put nodes in a different layer, a `CanvasLayer ` node can be used. Global canvas transform ----------------------- Viewports also have a Global Canvas transform (also a -:ref:`Transform2D `). This is the master transform and +`Transform2D `). This is the master transform and affects all individual *Canvas Layer* transforms. Generally, this transform is not of much use, but is used in the CanvasItem Editor in Godot's editor. @@ -37,13 +37,13 @@ Stretch transform Finally, viewports have a *Stretch Transform*, which is used when resizing or stretching the screen. This transform is used internally (as -described in :ref:`doc_multiple_resolutions`), but can also be manually set +described in `doc_multiple_resolutions`), but can also be manually set on each viewport. -Input events received in the :ref:`MainLoop._input_event() ` +Input events received in the `MainLoop._input_event() ` callback are multiplied by this transform but lack the ones above. To convert InputEvent coordinates to local CanvasItem coordinates, the -:ref:`CanvasItem.make_input_local() ` +`CanvasItem.make_input_local() ` function was added for convenience. Transform order @@ -62,11 +62,11 @@ Obtaining each transform can be achieved with the following functions: +----------------------------------+---------------------------------------------------------------------------------------------+ | Type | Transform | +==================================+=============================================================================================+ -| CanvasItem | :ref:`CanvasItem.get_global_transform() ` | +| CanvasItem | `CanvasItem.get_global_transform() ` | +----------------------------------+---------------------------------------------------------------------------------------------+ -| CanvasLayer | :ref:`CanvasItem.get_canvas_transform() ` | +| CanvasLayer | `CanvasItem.get_canvas_transform() ` | +----------------------------------+---------------------------------------------------------------------------------------------+ -| CanvasLayer+GlobalCanvas+Stretch | :ref:`CanvasItem.get_viewport_transform() ` | +| CanvasLayer+GlobalCanvas+Stretch | `CanvasItem.get_viewport_transform() ` | +----------------------------------+---------------------------------------------------------------------------------------------+ Finally, then, to convert a CanvasItem local coordinates to screen diff --git a/tutorials/2d/canvas_layers.rst b/tutorials/2d/canvas_layers.rst index 7e23e40..9c4f245 100644 --- a/tutorials/2d/canvas_layers.rst +++ b/tutorials/2d/canvas_layers.rst @@ -6,20 +6,20 @@ Canvas layers Viewport and Canvas items ------------------------- -:ref:`CanvasItem ` is the base for all 2D nodes, be it regular -2D nodes, such as :ref:`Node2D `, or :ref:`Control `. -Both inherit from :ref:`CanvasItem `. +`CanvasItem ` is the base for all 2D nodes, be it regular +2D nodes, such as `Node2D `, or `Control `. +Both inherit from `CanvasItem `. You can arrange canvas items in trees. Each item will inherit its parent's transform: when the parent moves, its children move too. CanvasItem nodes, and nodes inheriting from them, are direct or indirect children of a -:ref:`Viewport `, that display them. +`Viewport `, that display them. A Viewport has the property -:ref:`Viewport.canvas_transform `, -allows to apply a custom :ref:`Transform2D ` +`Viewport.canvas_transform `, +allows to apply a custom `Transform2D ` transform to the CanvasItem hierarchy it contains. Nodes such as -:ref:`Camera2D ` work by changing that transform. +`Camera2D ` work by changing that transform. To achieve effects like scrolling, manipulating the canvas transform property is more efficient than moving the root canvas item and the entire scene with it. @@ -37,7 +37,7 @@ How can these problems be solved in a single scene tree? CanvasLayers ------------ -The answer is :ref:`CanvasLayer `, +The answer is `CanvasLayer `, which is a node that adds a separate 2D rendering layer for all its children and grand-children. Viewport children will draw by default at layer "0", while a CanvasLayer will draw at any numeric layer. Layers @@ -61,4 +61,4 @@ their layer number, so they can be instantiated when needed. The standard way to ensuring that a node is correctly drawn 'in front' or 'behind' others is to manipulate the order of the nodes in the scene panel. Perhaps counterintuitively, the topmost nodes in the scene panel are drawn on *behind* lower ones in the viewport. 2d nodes also have a property for controlling their drawing order - (see :ref:`Node2D.z_index `). + (see `Node2D.z_index `). diff --git a/tutorials/2d/custom_drawing_in_2d.rst b/tutorials/2d/custom_drawing_in_2d.rst index 91c83ec..087c608 100644 --- a/tutorials/2d/custom_drawing_in_2d.rst +++ b/tutorials/2d/custom_drawing_in_2d.rst @@ -10,7 +10,7 @@ Godot has nodes to draw sprites, polygons, particles, and all sorts of stuff. For most cases, this is enough; but not always. Before crying in fear, angst, and rage because a node to draw that specific *something* does not exist... it would be good to know that it is possible to easily make any 2D node (be it -:ref:`Control ` or :ref:`Node2D ` +`Control ` or `Node2D ` based) draw custom commands. It is *really* easy to do it, too. Custom drawing in a 2D node is *really* useful. Here are some use cases: @@ -30,9 +30,9 @@ Custom drawing in a 2D node is *really* useful. Here are some use cases: Drawing ------- -Add a script to any :ref:`CanvasItem ` -derived node, like :ref:`Control ` or -:ref:`Node2D `. Then override the ``_draw()`` function. +Add a script to any `CanvasItem ` +derived node, like `Control ` or +`Node2D `. Then override the ``_draw()`` function. gdscript GDScript @@ -44,7 +44,7 @@ gdscript GDScript pass ``` -Draw commands are described in the :ref:`CanvasItem ` +Draw commands are described in the `CanvasItem ` class reference. There are plenty of them. Updating @@ -54,7 +54,7 @@ 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 :ref:`CanvasItem.update() ` +call `CanvasItem.update() ` in that same node and a new ``_draw()`` call will happen. Here is a little more complex example, a texture variable that will be @@ -308,11 +308,11 @@ Let's run again! This time, the rotation displays fine! Antialiased drawing ^^^^^^^^^^^^^^^^^^^ -Godot offers method parameters in :ref:`draw_line` +Godot offers method parameters in `draw_line` to enable antialiasing, but it doesn't work reliably in all situations (for instance, on mobile/web platforms, or when HDR is enabled). There is also no ``antialiased`` parameter available in -:ref:`draw_polygon`. +`draw_polygon`. As a workaround, install and use the `Antialiased Line2D add-on `__ @@ -324,4 +324,4 @@ Tools Drawing your own nodes might also be desired while running them in the editor. This can be used as a preview or visualization of some feature or -behavior. See :ref:`doc_running_code_in_the_editor` for more information. +behavior. See `doc_running_code_in_the_editor` for more information. diff --git a/tutorials/2d/particle_systems_2d.rst b/tutorials/2d/particle_systems_2d.rst index 9df80a6..155d9b9 100644 --- a/tutorials/2d/particle_systems_2d.rst +++ b/tutorials/2d/particle_systems_2d.rst @@ -20,13 +20,13 @@ parameters and then adding randomness to them. Particle nodes ~~~~~~~~~~~~~~ -Godot provides two different nodes for 2D particles, :ref:`class_Particles2D` and -:ref:`class_CPUParticles2D`. +Godot provides two different nodes for 2D particles, `class_Particles2D` and +`class_CPUParticles2D`. Particles2D is more advanced and uses the GPU to process particle effects, but that limits it to higher end graphics API, and in our case to the GLES3 renderer. For projects using the GLES2 backend, CPUParticles2D is a CPU-driven option with near feature parity with Particles2D, but lesser performance. While Particles2D is configured via a -:ref:`class_ParticlesMaterial` (and optionally with a custom shader), the matching options +`class_ParticlesMaterial` (and optionally with a custom shader), the matching options are provided via node properties in CPUParticles2D (with the exception of the trail settings). You can convert a Particles2D node into a CPUParticles2D node by clicking on the node in the inspector, and selecting "Convert to CPUParticles2D" in the "Particles" menu of the toolbar. diff --git a/tutorials/2d/using_tilemaps.rst b/tutorials/2d/using_tilemaps.rst index 6c852b1..898482c 100644 --- a/tutorials/2d/using_tilemaps.rst +++ b/tutorials/2d/using_tilemaps.rst @@ -7,9 +7,9 @@ Introduction ------------ A tilemap is a grid of tiles used to create a game's layout. There are several -benefits to using :ref:`TileMap ` nodes to design your levels. +benefits to using `TileMap ` nodes to design your levels. First, they make it possible to draw the layout by "painting" the tiles onto a -grid, which is much faster than placing individual :ref:`Sprite ` +grid, which is much faster than placing individual `Sprite ` nodes one by one. Second, they allow for much larger levels because they are optimized for drawing large numbers of tiles. Finally, you can add collision, occlusion, and navigation shapes to tiles, adding additional functionality to @@ -31,12 +31,12 @@ 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 :ref:`doc_import_images` for details. +off ``Filter`` and click "Reimport". See `doc_import_images` for details. TileMap node ------------ -Add a new :ref:`TileMap ` node to the scene. By default, a TileMap +Add a new `TileMap ` node to the scene. By default, a TileMap uses a square grid of tiles. You can also use a perspective-based "Isometric" mode or define your own custom tile shape. @@ -71,8 +71,8 @@ Creating a TileSet ------------------ Once you've configured your tilemap, it's time to add a -:ref:`TileSet `. A TileSet is a -:ref:`Resource ` that contains the data about your +`TileSet `. A TileSet is a +`Resource ` that contains the data about your tiles - their textures, collision shapes, and other properties. When the game runs, the TileMap combines the individual tiles into a single object. @@ -340,7 +340,7 @@ to take effect. Tips and tricks --------------- -- If you're using a :ref:`Camera2D ` to scroll your level, you +- If you're using a `Camera2D ` to scroll your level, you may notice lines appearing between your tiles. To fix this, open Project Settings and enable **Use Gpu Pixel Snap** in the **Rendering > 2d > Snapping** section. diff --git a/tutorials/3d/3d_rendering_limitations.rst b/tutorials/3d/3d_rendering_limitations.rst index bdfc12c..06bfe9b 100644 --- a/tutorials/3d/3d_rendering_limitations.rst +++ b/tutorials/3d/3d_rendering_limitations.rst @@ -7,7 +7,7 @@ In addition to the limitations below, mobile platforms have even more limitations on 3D rendering compared to desktop platforms. - See :ref:`doc_mobile_rendering_limitations` for more information. + See `doc_mobile_rendering_limitations` for more information. Introduction ------------ @@ -91,7 +91,7 @@ In Godot, transparent materials are drawn after opaque materials. Transparent objects are sorted back to front before being drawn based on the Spatial's position, not the vertex position in world space. Due to this, overlapping objects may often be sorted out of order. To fix improperly sorted objects, tweak -the material's :ref:`Render Priority ` +the material's `Render Priority ` property. This will force specific materials to appear in front or behind of other transparent materials. Even then, this may not always be sufficient. diff --git a/tutorials/3d/3d_text.rst b/tutorials/3d/3d_text.rst index 96a15cc..c63ee0c 100644 --- a/tutorials/3d/3d_text.rst +++ b/tutorials/3d/3d_text.rst @@ -30,7 +30,7 @@ up and shaded by light sources if the shaded flag is enabled, but it will not cast a shadow, even with cast shadow turned on under the nodes GeometryInstance3D settings. This is because the node is a quad mesh (one glyph per quad) with transparent textures and has the same limitations -as Sprite3D. See :ref:`this page ` +as Sprite3D. See `this page ` for more information. Text mesh diff --git a/tutorials/3d/baked_lightmaps.rst b/tutorials/3d/baked_lightmaps.rst index 517a71f..869391e 100644 --- a/tutorials/3d/baked_lightmaps.rst +++ b/tutorials/3d/baked_lightmaps.rst @@ -7,14 +7,14 @@ Introduction ------------ Baked lightmaps are an alternative workflow for adding indirect (or fully baked) -lighting to a scene. Unlike the :ref:`doc_gi_probes` approach, baked lightmaps +lighting to a scene. Unlike the `doc_gi_probes` approach, baked lightmaps work fine on low-end PCs and mobile devices, as they consume almost no resources at run-time. Also unlike GIProbe, baked lightmaps can optionally be used to store direct lighting, which provides even further performance gains. Unlike GIProbes, Baked Lightmaps are completely static. Once baked, they can't be modified at all. They also don't provide the scene with reflections, so -using :ref:`doc_reflection_probes` together with it on interiors (or using a Sky +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 @@ -26,7 +26,7 @@ bake lightmaps only when you actually need to see changes in lighting. Baking lightmaps will also reserve baked materials' UV2 slot, which means you can no longer use it for other purposes in materials (either in the built-in -:ref:`doc_spatial_material` or in custom shaders). +`doc_spatial_material` or in custom shaders). In the end, deciding which indirect lighting approach is better depends on your use case. In general, GIProbe is easier to set up and works better with dynamic @@ -333,7 +333,7 @@ Capture - **Quality:** The lightmap probe generation quality. Higher values result in more accurate lighting, but take longer to bake. This setting does not affect the *density* of the lightmap probes, only their quality. -- **Propagation:** Similar to :ref:`GIProbe `'s Propagation property. +- **Propagation:** Similar to `GIProbe `'s Propagation property. Higher values result in brighter and more diffuse indirect lighting for dynamic objects. Adjust this value depending on your scene to make dynamic objects better fit with static baked lighting. diff --git a/tutorials/3d/csg_tools.rst b/tutorials/3d/csg_tools.rst index 9af965e..d978415 100644 --- a/tutorials/3d/csg_tools.rst +++ b/tutorials/3d/csg_tools.rst @@ -29,13 +29,13 @@ Introduction to CSG nodes Like other features of Godot, CSG is supported in the form of nodes. These are the CSG nodes: -- :ref:`CSGBox ` -- :ref:`CSGCylinder ` (also supports cone) -- :ref:`CSGSphere ` -- :ref:`CSGTorus ` -- :ref:`CSGPolygon ` -- :ref:`CSGMesh ` -- :ref:`CSGCombiner ` +- `CSGBox ` +- `CSGCylinder ` (also supports cone) +- `CSGSphere ` +- `CSGTorus ` +- `CSGPolygon ` +- `CSGMesh ` +- `CSGCombiner ` .. image:: img/csg_nodes.png @@ -59,7 +59,7 @@ Every CSG node supports 3 kinds of boolean operations: CSGPolygon ~~~~~~~~~~ -The :ref:`CSGPolygon ` node extrude along a Polygon drawn in +The `CSGPolygon ` node extrude along a Polygon drawn in 2D (in X, Y coordinates) in the following ways: - **Depth:** Extruded back a given amount. @@ -71,7 +71,7 @@ The :ref:`CSGPolygon ` node extrude along a Polygon drawn in .. image:: img/csg_poly.png -.. note:: The **Path** mode must be provided with a :ref:`Path ` +.. note:: The **Path** mode must be provided with a `Path ` node to work. In the Path node, draw the path and the polygon in CSGPolygon will extrude along the given path. @@ -79,7 +79,7 @@ The :ref:`CSGPolygon ` node extrude along a Polygon drawn in Custom meshes ~~~~~~~~~~~~~ -Any mesh can be used for :ref:`CSGMesh `; the mesh can be +Any mesh can be used for `CSGMesh `; the mesh can be modelled in other software and imported into Godot. Multiple materials are supported. There are some restrictions for geometry: @@ -93,7 +93,7 @@ supported. There are some restrictions for geometry: CSGCombiner ~~~~~~~~~~~ -The :ref:`CSGCombiner ` node is an empty shape used for +The `CSGCombiner ` node is an empty shape used for organization. It will only combine children nodes. Processing order @@ -249,7 +249,7 @@ or a city; explore its limitations when designing your game. Using prototype textures ------------------------ -Godot's :ref:`doc_spatial_material` supports *triplanar mapping*, which can be +Godot's `doc_spatial_material` supports *triplanar mapping*, which can be used to automatically apply a texture to arbitrary objects without distortion. This is handy when using CSG as Godot doesn't support editing UV maps on CSG nodes yet. Triplanar mapping is relatively slow, which usually restricts its diff --git a/tutorials/3d/gi_probes.rst b/tutorials/3d/gi_probes.rst index 9af9859..ccdd52c 100644 --- a/tutorials/3d/gi_probes.rst +++ b/tutorials/3d/gi_probes.rst @@ -7,11 +7,11 @@ Introduction ------------ .. note:: This feature is only available when using the GLES3 backend. - :ref:`doc_baked_lightmaps` can be used as an alternative + `doc_baked_lightmaps` can be used as an alternative when using the GLES2 renderer. -Just like with :ref:`doc_reflection_probes`, and as stated in -the :ref:`doc_spatial_material`, objects can show reflected or diffuse light. +Just like with `doc_reflection_probes`, and as stated in +the `doc_spatial_material`, objects can show reflected or diffuse light. GI Probes are similar to Reflection Probes, but they use a different and more complex technique to produce indirect light and reflections. diff --git a/tutorials/3d/high_dynamic_range.rst b/tutorials/3d/high_dynamic_range.rst index 5d9327e..fd6947d 100644 --- a/tutorials/3d/high_dynamic_range.rst +++ b/tutorials/3d/high_dynamic_range.rst @@ -101,7 +101,7 @@ Scene linear to display-referred nonlinear After all the rendering is done, the scene linear render requires transforming to a suitable output such as an sRGB display. To do this, enable sRGB conversion -in the current :ref:`Environment ` (more on that below). +in the current `Environment ` (more on that below). Keep in mind that the **sRGB -> Display Linear** and **Display Linear -> sRGB** conversions must always be **both** enabled. Failing to enable one of them will @@ -111,8 +111,8 @@ indie games. Parameters of HDR ----------------- -HDR settings can be found in the :ref:`Environment ` +HDR settings can be found in the `Environment ` resource. Most of the time, these are found inside a -:ref:`WorldEnvironment ` +`WorldEnvironment ` node or set in a Camera node. For more information, see -:ref:`doc_environment_and_post_processing`. +`doc_environment_and_post_processing`. diff --git a/tutorials/3d/introduction_to_3d.rst b/tutorials/3d/introduction_to_3d.rst index b8aa39b..c7d55dc 100644 --- a/tutorials/3d/introduction_to_3d.rst +++ b/tutorials/3d/introduction_to_3d.rst @@ -12,16 +12,16 @@ the 3D platformer tutorial, or the 3D kinematic character tutorials, which are almost identical to their 2D counterparts. In 3D, math is a little more complex than in 2D, so also checking the -:ref:`doc_vector_math` entry in the wiki (which was especially created for game +`doc_vector_math` entry in the wiki (which was especially created for game developers, not mathematicians or engineers) will help pave the way for you to develop 3D games efficiently. Spatial node ~~~~~~~~~~~~ -:ref:`Node2D ` is the base node for 2D. -:ref:`Control ` is the base node for everything GUI. -Following this reasoning, the 3D engine uses the :ref:`Spatial ` +`Node2D ` is the base node for 2D. +`Control ` is the base node for everything GUI. +Following this reasoning, the 3D engine uses the `Spatial ` node for everything 3D. .. image:: img/tuto_3d1.png @@ -29,7 +29,7 @@ node for everything 3D. Spatial nodes have a local transform, which is relative to the parent node (as long as the parent node is also of **or inherits from** the type Spatial). This transform can be accessed as a 4×3 -:ref:`Transform `, or as 3 :ref:`Vector3 ` +`Transform `, or as 3 `Vector3 ` members representing location, Euler rotation (X, Y and Z angles) and scale. @@ -51,21 +51,21 @@ DCC-created models (used to reference a non existing doc_importing_3d_meshes importer). There are two pipelines to import 3D models in Godot. The first and most -common one is by :ref:`doc_importing_3d_scenes`, which allows you to import +common one is by `doc_importing_3d_scenes`, which allows you to import entire scenes (just as they look in the DCC), including animation, skeletal rigs, blend shapes, etc. The second pipeline is by importing simple .OBJ files as mesh resources, -which can be then put inside a :ref:`MeshInstance ` +which can be then put inside a `MeshInstance ` node for display. Generated geometry ------------------ It is possible to create custom geometry by using the -:ref:`ArrayMesh ` resource directly. Simply create your arrays -and use the :ref:`ArrayMesh.add_surface_from_arrays() ` -function. A helper class is also available, :ref:`SurfaceTool `, +`ArrayMesh ` resource directly. Simply create your arrays +and use the `ArrayMesh.add_surface_from_arrays() ` +function. A helper class is also available, `SurfaceTool `, which provides a more straightforward API and helpers for indexing, generating normals, tangents, etc. @@ -78,7 +78,7 @@ Immediate geometry If, instead, there is a requirement to generate simple geometry that will be updated often, Godot provides a special node, -:ref:`ImmediateGeometry `, +`ImmediateGeometry `, which provides an OpenGL 1.x style immediate-mode API to create points, lines, triangles, etc. @@ -88,8 +88,8 @@ lines, triangles, etc. While Godot packs a powerful 2D engine, many types of games use 2D in a 3D environment. By using a fixed camera (either orthogonal or perspective) that does not rotate, nodes such as -:ref:`Sprite3D ` and -:ref:`AnimatedSprite3D ` +`Sprite3D ` and +`AnimatedSprite3D ` can be used to create 2D games that take advantage of mixing with 3D backgrounds, more realistic parallax, lighting/shadow effects, etc. @@ -101,7 +101,7 @@ Environment ~~~~~~~~~~~ Besides editing a scene, it is often common to edit the environment. -Godot provides a :ref:`WorldEnvironment ` +Godot provides a `WorldEnvironment ` node that allows changing the background color, mode (as in, put a skybox), and applying several types of built-in post-processing effects. Environments can also be overridden in the Camera. @@ -193,7 +193,7 @@ Cameras ------- No matter how many objects are placed in the 3D space, nothing will be -displayed unless a :ref:`Camera ` is +displayed unless a `Camera ` is also added to the scene. Cameras can work in either orthogonal or perspective projections: diff --git a/tutorials/3d/lights_and_shadows.rst b/tutorials/3d/lights_and_shadows.rst index 57846ba..18b2e82 100644 --- a/tutorials/3d/lights_and_shadows.rst +++ b/tutorials/3d/lights_and_shadows.rst @@ -13,11 +13,11 @@ result. Light can come from several types of sources in a scene: it does not affect nearby objects unless baked). - Light Nodes: Directional, Omni and Spot. - Ambient Light in the - :ref:`Environment `. -- Baked Light (read :ref:`doc_baked_lightmaps`). + `Environment `. +- Baked Light (read `doc_baked_lightmaps`). The emission color is a material property. You can read more about it -in the :ref:`doc_spatial_material` tutorial. +in the `doc_spatial_material` tutorial. Light nodes ----------- @@ -31,11 +31,11 @@ parameters for lights: Each one has a specific function: - **Color**: Base color for emitted light. -- **Energy**: Energy multiplier. This is useful for saturating lights or working with :ref:`doc_high_dynamic_range`. +- **Energy**: Energy multiplier. This is useful for saturating lights or working with `doc_high_dynamic_range`. - **Indirect Energy**: Secondary multiplier used with indirect light (light bounces). This works in baked light or GIProbe. - **Negative**: Light becomes subtractive instead of additive. It's sometimes useful to manually compensate some dark corners. - **Specular**: Affects the intensity of the specular blob in objects affected by this light. At zero, this light becomes a pure diffuse light. -- **Bake Mode**: Sets the bake mode for the light. For more information see :ref:`doc_baked_lightmaps` +- **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 diff --git a/tutorials/3d/occluders.rst b/tutorials/3d/occluders.rst index cd20f31..29d79cc 100644 --- a/tutorials/3d/occluders.rst +++ b/tutorials/3d/occluders.rst @@ -3,9 +3,9 @@ Occluder Nodes ============== -In addition to occlusion via :ref:`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 :ref:`doc_rooms_and_portals`. Nevertheless they can still significantly boost performance in some situations. +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. diff --git a/tutorials/3d/portals/advanced_room_and_portal_usage.rst b/tutorials/3d/portals/advanced_room_and_portal_usage.rst index c059bfe..94f8ddf 100644 --- a/tutorials/3d/portals/advanced_room_and_portal_usage.rst +++ b/tutorials/3d/portals/advanced_room_and_portal_usage.rst @@ -17,7 +17,7 @@ This works because if a monster is in an area that is completely out of view for 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 :ref:`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. +This problem is solved because the portal system contains a subsystem called the **Gameplay Monitor** that can be turned on and off from the `RoomManager`. When switched on, any roaming objects that move inside or outside the gameplay area (whether by moving themselves, or the camera moving) will receive callbacks to let them know of this change. You can choose to either receive these callbacks as ``signals``, or as ``notifications``. @@ -41,7 +41,7 @@ VisbilityNotifiers / VisibilityEnablers Gameplay callbacks have one more useful function. By default in Godot, animation and physics are still processed regardless of whether an object is within view. This can sap performance, especially when using software skinning. -The engine's solution to this problem is the :ref:`VisibilityNotifier` node, and its slightly easier to use variation, the :ref:`VisibilityEnabler` node. VisibilityEnabler can be used to switch off animation and sleep physics when an object is outside the view frustum. You do this by simply placing a VisibilityEnabler node in your subscene (for e.g. a monster). It will do the rest. Consult the :ref:`VisibilityEnabler` documentation for full details. +The engine's solution to this problem is the `VisibilityNotifier` node, and its slightly easier to use variation, the `VisibilityEnabler` node. VisibilityEnabler can be used to switch off animation and sleep physics when an object is outside the view frustum. You do this by simply placing a VisibilityEnabler node in your subscene (for e.g. a monster). It will do the rest. Consult the `VisibilityEnabler` documentation for full details. .. image:: img/visibility_enabler.png @@ -52,11 +52,11 @@ What if the VisibilityEnabler could turn off objects when they were occlusion cu RoomGroups ~~~~~~~~~~ -A :ref:`RoomGroup` is a special node which allows you to deal with a group of rooms at once, instead of having write code for them individually. This is especially useful in conjunction with gameplay callbacks. The most important use for RoomGroups is to delineate between "inside" and "outside" areas. +A `RoomGroup` is a special node which allows you to deal with a group of rooms at once, instead of having write code for them individually. This is especially useful in conjunction with gameplay callbacks. The most important use for RoomGroups is to delineate between "inside" and "outside" areas. .. image:: img/roomgroups.png -For instance, when outside you may wish to use a :ref:`DirectionalLight` to represent the sun. When the outside RoomGroup receives an ``enter gameplay`` callback, you can turn the light on, and you can turn it off when the RoomGroup exits gameplay. With the light off, performance will increase as there is no need to render it indoors. +For instance, when outside you may wish to use a `DirectionalLight` to represent the sun. When the outside RoomGroup receives an ``enter gameplay`` callback, you can turn the light on, and you can turn it off when the RoomGroup exits gameplay. With the light off, performance will increase as there is no need to render it indoors. This is an example of a simple RoomGroup script to turn on and off a DirectionalLight. Note that you can also use signals for callbacks (the choice is up to you): diff --git a/tutorials/3d/portals/editing_rooms_and_portals.rst b/tutorials/3d/portals/editing_rooms_and_portals.rst index da3bb0d..1e47041 100644 --- a/tutorials/3d/portals/editing_rooms_and_portals.rst +++ b/tutorials/3d/portals/editing_rooms_and_portals.rst @@ -8,9 +8,9 @@ Putting all the ideas together, here is an example scene tree: .. image:: img/example_scenetree.png -- We have used a :ref:`RoomGroup` to denote an outside area. -- The :ref:`MeshInstance`\ s inside the :ref:`Room`\ s are either ``STATIC`` or ``DYNAMIC``. -- We have created a :ref:`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 +- We have used a `RoomGroup` to denote an outside area. +- The `MeshInstance`\ s inside the `Room`\ s are either ``STATIC`` or ``DYNAMIC``. +- We have created a `Spatial` (I decided to call it 'Freeform', but you could use any name) under which to place ``STATIC`` and ``DYNAMIC`` objects that will be autoplaced in rooms (Freeform is inside the ``roomlist``, but *not* inside a room.) - The player and the monsters are on branches *OUTSIDE* the ``roomlist``. - The player and monster meshes have portal mode ``ROAMING`` so they can be in any room. @@ -26,9 +26,9 @@ Although you can create your room system entirely within the editor, you can als Postfix convention ^^^^^^^^^^^^^^^^^^ -- ``-room`` becomes a :ref:`Room`. -- ``-roomgroup`` becomes a :ref:`RoomGroup`. -- ``-portal`` becomes a :ref:`Portal`. +- ``-room`` becomes a `Room`. +- ``-roomgroup`` becomes a `RoomGroup`. +- ``-portal`` becomes a `Portal`. - ``-bound`` becomes a manual bound. Rooms and RoomGroups should be created as Empties within Blender. Any mesh children of the ``-room`` Empty will thus be placed in the Room during conversion in Godot. @@ -44,7 +44,7 @@ Portals Portals are different from Rooms. In Portals, we need to specify the geometry of the Portal in our modelling tool, in addition to just the name. To do this your "portal-to-be" should be created as a Mesh. -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 :ref:`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. +Portal meshes have some restrictions to work properly. They must be convex, and the polygon points should be in the same plane. The accuracy to the plane does not have to be exact, as Godot will automatically average the direction of the portal plane. Once converted to a `Portal` node, the snapping to the portal plane is enforced, and the vertices are specified (and editable) as 2D coordinates in the inspector, rather than 3D points. The portal's naming is quite important. You can either name the portal ``-portal`` which will attempt to autolink the Portal in Godot, or you can use the name of the Room you wish to link the Portal to as a prefix. diff --git a/tutorials/3d/portals/first_steps_with_rooms_and_portals.rst b/tutorials/3d/portals/first_steps_with_rooms_and_portals.rst index 8948f78..0273340 100644 --- a/tutorials/3d/portals/first_steps_with_rooms_and_portals.rst +++ b/tutorials/3d/portals/first_steps_with_rooms_and_portals.rst @@ -4,7 +4,7 @@ First steps with Rooms and Portals The RoomManager ~~~~~~~~~~~~~~~ -Anytime you want to use the portal system, you need to include a special node in your scene tree, called the :ref:`RoomManager`. The RoomManager is responsible for the runtime maintenance of the system, especially converting the objects in your rooms into a *room graph* which is used at runtime to perform occlusion culling and other tasks. +Anytime you want to use the portal system, you need to include a special node in your scene tree, called the `RoomManager`. The RoomManager is responsible for the runtime maintenance of the system, especially converting the objects in your rooms into a *room graph* which is used at runtime to perform occlusion culling and other tasks. Room Conversion ^^^^^^^^^^^^^^^ @@ -40,7 +40,7 @@ Rooms What is a room? ^^^^^^^^^^^^^^^ -:ref:`Room`\ s are a way of spatially partitioning your level into areas that make sense in terms of level design. Rooms often quite literally *are* rooms (like in a building). Ultimately though, as far as the engine is concerned, a room represents a **non-overlapping** convex volume in which you typically place most of your objects that fall within that area. +`Room`\ s are a way of spatially partitioning your level into areas that make sense in terms of level design. Rooms often quite literally *are* rooms (like in a building). Ultimately though, as far as the engine is concerned, a room represents a **non-overlapping** convex volume in which you typically place most of your objects that fall within that area. A room doesn't need to correspond to a literal room. It could, for example, also be a canyon in an outdoor area or a smaller part of a concave room. With a little imagination, you can use the system in almost any scenario. @@ -64,12 +64,12 @@ If you accidentally create overlapping rooms, the editor will warn you when you The system does attempt to cope with overlapping rooms as best as possible by making the current room *"sticky"*. Each object remembers which room it was in during the previous frame and stays within it as long as it does not move outside the convex hull room bound. This can result in some hysteresis in these overlapping zones. -There is one exception, however, for :ref:`internal rooms`. You do not have to worry about these to start with. +There is one exception, however, for `internal rooms`. You do not have to worry about these to start with. How do I create a room? ^^^^^^^^^^^^^^^^^^^^^^^ -A :ref:`Room` is a node type that can be added to the scene tree like any other. You can place objects within the room by making them children and grand-children of the Room node. +A `Room` is a node type that can be added to the scene tree like any other. You can place objects within the room by making them children and grand-children of the Room node. How do I define the shape and position of my room convex hull? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -77,8 +77,8 @@ How do I define the shape and position of my room convex hull? Because defining the room bound is the most important aspect of the system, there are THREE methods available to define the shape of a room in Godot: 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 :ref:`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 :ref:`doc_rooms_and_portals_blender`). +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`). 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. -:ref:`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`` :ref:`MeshInstance`. You can add or remove points using the inspector. A portal requires at least 3 points to work - this is because it needs to form a polygon rather than a point or line. +`Portal`\ s are special convex polygons that you position over the openings between rooms in order to allow the system to see between them. You can create a portal node directly in the editor. The default portal has 4 points and behaves much like a ``plane`` `MeshInstance`. You can add or remove points using the inspector. A portal requires at least 3 points to work - this is because it needs to form a polygon rather than a point or line. To save editing effort, **only one Portal is required between each pair of Rooms**. You *do not need* to (and indeed should not) create two Portals that overlap in opposite directions. Portals default to being two-way, but you can make them one-way in the Portal inspector. diff --git a/tutorials/3d/portals/introduction_to_rooms_and_portals.rst b/tutorials/3d/portals/introduction_to_rooms_and_portals.rst index 398c369..b5e9645 100644 --- a/tutorials/3d/portals/introduction_to_rooms_and_portals.rst +++ b/tutorials/3d/portals/introduction_to_rooms_and_portals.rst @@ -3,7 +3,7 @@ Introduction to Rooms and Portals ================================= -The rooms and portals system is an optional component of Godot that allows you to partition your 3D game levels into a series of :ref:`Room` s (*aka cells*), and :ref:`Portal` s. Portals are openings between the rooms that the :ref:`Camera` (and lights) can see through. +The rooms and portals system is an optional component of Godot that allows you to partition your 3D game levels into a series of `Room` s (*aka cells*), and `Portal` s. Portals are openings between the rooms that the `Camera` (and lights) can see through. This allows several features: diff --git a/tutorials/3d/portals/rooms_and_portals_example.rst b/tutorials/3d/portals/rooms_and_portals_example.rst index 06cceb1..006c5e1 100644 --- a/tutorials/3d/portals/rooms_and_portals_example.rst +++ b/tutorials/3d/portals/rooms_and_portals_example.rst @@ -16,13 +16,13 @@ Step 1 .. image:: tutorial_simple/img/tutorial_simple_1.png - Create a new project. -- Add a :ref:`Spatial` as the scene root (on the screenshot, it's called "Root"). -- Next add a :ref:`RoomManager` node. We will need this later to process the room system. +- Add a `Spatial` as the scene root (on the screenshot, it's called "Root"). +- Next add a `RoomManager` node. We will need this later to process the room system. - Next we need to start defining our rooms. We create all our rooms under another Spatial we have called 'RoomList'. -- Add a new :ref:`Room` node as a child of the roomlist. +- Add a new `Room` node as a child of the roomlist. - 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 :ref:`MeshInstance` for the floor. Create a box by adding a CubeMesh resource to the MeshInstance. Scale and position it to form a floor. +- Create a `MeshInstance` for the floor. Create a box by adding a CubeMesh resource to the MeshInstance. Scale and position it to form a floor. - Create MeshInstances for the walls. Create more box meshes for this, then scale and position them. Be sure to leave an opening on one side. You will need to create two wall segments to do this on that side. Step 2 @@ -41,7 +41,7 @@ Step 3 .. image:: tutorial_simple/img/tutorial_simple_3.png - Next, we will add a portal between the two rooms. -- Create a new :ref:`Portal` in the kitchen. +- Create a new `Portal` in the kitchen. - Scale and position the portal using the node ``Transform`` in the inspector, so it fits within the opening between the two rooms. - 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. @@ -54,7 +54,7 @@ Step 4 - 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. - 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 :ref:`OmniLight` so it will be autoplaced in one of the rooms. +- Let's also create an `OmniLight` so it will be autoplaced in one of the rooms. Step 5 ~~~~~~ diff --git a/tutorials/3d/portals/using_objects_in_rooms_and_portals.rst b/tutorials/3d/portals/using_objects_in_rooms_and_portals.rst index 949956e..50c03a9 100644 --- a/tutorials/3d/portals/using_objects_in_rooms_and_portals.rst +++ b/tutorials/3d/portals/using_objects_in_rooms_and_portals.rst @@ -1,12 +1,12 @@ Using objects in Rooms and Portals ================================== -Normally, when you use Godot, all objects that you can see (:ref:`VisualInstance`\ s) are treated in the same way by the engine. The portal renderer is slightly different, in that it makes a distinction between the different roles objects will have in your game. It makes this distinction to define the :ref:`Room`\ s, and to render and process everything in the most efficient way. +Normally, when you use Godot, all objects that you can see (`VisualInstance`\ s) are treated in the same way by the engine. The portal renderer is slightly different, in that it makes a distinction between the different roles objects will have in your game. It makes this distinction to define the `Room`\ s, and to render and process everything in the most efficient way. Portal mode ~~~~~~~~~~~ -If you look in the inspector, every VisualInstance in Godot is derived from a :ref:`CullInstance`, where you can set a ``PortalMode``. This determines how objects will behave in the portal system. +If you look in the inspector, every VisualInstance in Godot is derived from a `CullInstance`, where you can set a ``PortalMode``. This determines how objects will behave in the portal system. .. image:: img/cull_instance.png @@ -90,6 +90,6 @@ While sprawling works great for large moving objects, it also gives you a lot mo Lighting ~~~~~~~~ -In general lights are handled like any other visual instance. They can be placed in rooms, and they will sprawl to affect neighbouring rooms, following the dimensions and direction of the light. The exception to this is :ref:`DirectionalLight`\ s. DirectionalLights have no source room as they affect *everywhere*. They should therefore not be placed in a room. As DirectionalLights can be expensive, it is a good idea to turn them off when inside, see the later :ref:`doc_rooms_and_portals_roomgroups` section for details on how to do this. +In general lights are handled like any other visual instance. They can be placed in rooms, and they will sprawl to affect neighbouring rooms, following the dimensions and direction of the light. The exception to this is `DirectionalLight`\ s. DirectionalLights have no source room as they affect *everywhere*. They should therefore not be placed in a room. As DirectionalLights can be expensive, it is a good idea to turn them off when inside, see the later `doc_rooms_and_portals_roomgroups` section for details on how to do this. Congratulations! You have now mastered the intermediate techniques required to use rooms and portals. You can use these to make games already, but there are many more features. diff --git a/tutorials/3d/procedural_geometry/arraymesh.rst b/tutorials/3d/procedural_geometry/arraymesh.rst index 86cef9a..6a27052 100644 --- a/tutorials/3d/procedural_geometry/arraymesh.rst +++ b/tutorials/3d/procedural_geometry/arraymesh.rst @@ -3,21 +3,21 @@ Using the ArrayMesh =================== -This tutorial will present the basics of using an :ref:`ArrayMesh `. +This tutorial will present the basics of using an `ArrayMesh `. -To do so, we will use the function :ref:`add_surface_from_arrays() `, +To do so, we will use the function `add_surface_from_arrays() `, which takes up to four parameters. The first two are required, while the second two are optional. The first parameter is the ``PrimitiveType``, an OpenGL concept that instructs the GPU how to arrange the primitive based on the vertices given, i.e. whether they represent triangles, -lines, points, etc. See :ref:`Mesh.PrimitiveType ` for the options available. +lines, points, etc. See `Mesh.PrimitiveType ` for the options available. The second parameter, ``arrays``, is the actual Array that stores the mesh information. The array is a normal Godot array that is constructed with empty brackets ``[]``. It stores a ``Pool**Array`` (e.g. PoolVector3Array, PoolIntArray, etc.) for each type of information that will be used to build the surface. The possible elements of ``arrays`` are listed below, together with the position they must have within ``arrays``. -See also :ref:`Mesh.ArrayType `. +See also `Mesh.ArrayType `. .. list-table:: @@ -32,40 +32,40 @@ See also :ref:`Mesh.ArrayType `. * - 0 - ``ARRAY_VERTEX`` - - :ref:`PoolVector3Array ` or :ref:`PoolVector2Array ` + - `PoolVector3Array ` or `PoolVector2Array ` * - 1 - ``ARRAY_NORMAL`` - - :ref:`PoolVector3Array ` + - `PoolVector3Array ` * - 2 - ``ARRAY_TANGENT`` - - :ref:`PoolRealArray ` of groups of 4 floats. First 3 floats determine the tangent, and + - `PoolRealArray ` of groups of 4 floats. First 3 floats determine the tangent, and the last the binormal direction as -1 or 1. * - 3 - ``ARRAY_COLOR`` - - :ref:`PoolColorArray ` + - `PoolColorArray ` * - 4 - ``ARRAY_TEX_UV`` - - :ref:`PoolVector2Array ` or :ref:`PoolVector3Array ` + - `PoolVector2Array ` or `PoolVector3Array ` * - 5 - ``ARRAY_TEX_UV2`` - - :ref:`PoolVector2Array ` or :ref:`PoolVector3Array ` + - `PoolVector2Array ` or `PoolVector3Array ` * - 6 - ``ARRAY_BONES`` - - :ref:`PoolRealArray ` of groups of 4 floats or :ref:`PoolIntArray ` of groups of 4 ints. Each group lists indexes of 4 bones that affects a given vertex. + - `PoolRealArray ` of groups of 4 floats or `PoolIntArray ` of groups of 4 ints. Each group lists indexes of 4 bones that affects a given vertex. * - 7 - ``ARRAY_WEIGHTS`` - - :ref:`PoolRealArray ` of groups of 4 floats. Each float lists the amount of weight an determined bone on ``ARRAY_BONES`` has on a given vertex. + - `PoolRealArray ` of groups of 4 floats. Each float lists the amount of weight an determined bone on ``ARRAY_BONES`` has on a given vertex. * - 8 - ``ARRAY_INDEX`` - - :ref:`PoolIntArray ` + - `PoolIntArray ` The array of vertices (at index 0) is always required. The index array is optional and will only be used if included. We won't use it in this tutorial. @@ -73,12 +73,12 @@ All the other arrays carry information about the vertices. They are also optiona use one entry per vertex to provide extra information about vertices. They must have the same size as the vertex array. Other arrays (e.g. ``ARRAY_TANGENT``) use four entries to describe a single vertex. These must be exactly four times larger than the vertex array. -For normal usage, the last two parameters in :ref:`add_surface_from_arrays() ` are typically left empty. +For normal usage, the last two parameters in `add_surface_from_arrays() ` are typically left empty. ArrayMesh --------- -In the editor, create a :ref:`MeshInstance ` and add an :ref:`ArrayMesh ` to it in the Inspector. +In the editor, create a `MeshInstance ` and add an `ArrayMesh ` to it in the Inspector. Normally, adding an ArrayMesh in the editor is not useful, but in this case it allows us to access the ArrayMesh from code without creating one. @@ -239,7 +239,7 @@ gdscript GDScript Saving ------ -Finally, we can use the :ref:`ResourceSaver ` class to save the ArrayMesh. +Finally, we can use the `ResourceSaver ` class to save the ArrayMesh. This is useful when you want to generate a mesh and then use it later without having to re-generate it. gdscript GDScript diff --git a/tutorials/3d/procedural_geometry/immediategeometry.rst b/tutorials/3d/procedural_geometry/immediategeometry.rst index a60a946..9019eca 100644 --- a/tutorials/3d/procedural_geometry/immediategeometry.rst +++ b/tutorials/3d/procedural_geometry/immediategeometry.rst @@ -3,7 +3,7 @@ Using ImmediateGeometry ======================= -Unlike the SurfaceTool or ArrayMesh, :ref:`ImmediateGeometry ` is an actual +Unlike the SurfaceTool or ArrayMesh, `ImmediateGeometry ` is an actual node. Being a node makes it quick to add to a scene and get visual output. It uses an OpenGL 1.x-style API like SurfaceTool, but it's actually designed to create meshes on the fly. @@ -17,7 +17,7 @@ not call ``clear()``. To begin generating geometry you must call ``begin()``. ``begin()`` takes a ``PrimitiveType`` as an argument. ``PrimitiveType`` is an OpenGL concept that instructs the GPU how to arrange the primitive based on the vertices given whether it is triangles, lines, points, etc. A complete list can be found under -the :ref:`Mesh ` class reference page. +the `Mesh ` class reference page. Once you have called ``begin()`` you are ready to start adding vertices. You add vertices one at a time. First you add vertex specific attributes such as normals or UVs using ``set_****()`` (e.g. ``set_normal()``). diff --git a/tutorials/3d/procedural_geometry/index.rst b/tutorials/3d/procedural_geometry/index.rst index 95e53f4..bdc6150 100644 --- a/tutorials/3d/procedural_geometry/index.rst +++ b/tutorials/3d/procedural_geometry/index.rst @@ -25,9 +25,9 @@ by an array of positions called "vertices". In Godot, geometry is represented by What is a Mesh? --------------- -Many things in Godot have mesh in their name: the :ref:`Mesh `, the :ref:`ArrayMesh `, -the :ref:`MeshInstance `, the :ref:`MultiMesh `, and -the :ref:`MultiMeshInstance `. While they are all related, they have slightly different uses. +Many things in Godot have mesh in their name: the `Mesh `, the `ArrayMesh `, +the `MeshInstance `, the `MultiMesh `, and +the `MultiMeshInstance `. While they are all related, they have slightly different uses. Meshes and ArrayMeshes are resources that are drawn using a MeshInstance node. Resources like Meshes and ArrayMeshes cannot be added to the scene directly. A MeshInstance represents one @@ -47,22 +47,22 @@ What a Mesh is A Mesh is composed of one or more surfaces. A surface is an array composed of multiple sub-arrays containing vertices, normals, UVs, etc. Normally the process of constructing surfaces and meshes is -hidden from the user in the :ref:`VisualServer `, but with ArrayMeshes, the user can construct a Mesh +hidden from the user in the `VisualServer `, but with ArrayMeshes, the user can construct a Mesh manually by passing in an array containing the surface information. Surfaces ^^^^^^^^ Each surface has its own material. Alternatively, you can override the material for all surfaces -in the Mesh when you use a MeshInstance using the :ref:`material_override ` property. +in the Mesh when you use a MeshInstance using the `material_override ` property. Surface array ^^^^^^^^^^^^^ The surface array is an array of length ``ArrayMesh.ARRAY_MAX``. Each position in the array is filled with a sub-array containing per-vertex information. For example, the array located at -``ArrayMesh.ARRAY_NORMAL`` is a :ref:`PoolVector3Array ` of vertex normals. -See :ref:`Mesh.ArrayType ` for more information. +``ArrayMesh.ARRAY_NORMAL`` is a `PoolVector3Array ` of vertex normals. +See `Mesh.ArrayType ` for more information. The surface array can be indexed or non-indexed. Creating a non-indexed array is as easy as not assigning an array at the index ``ArrayMesh.ARRAY_INDEX``. A non-indexed array stores unique vertex information for @@ -84,7 +84,7 @@ ArrayMesh The ArrayMesh resource extends Mesh to add a few different quality of life functions and, most importantly, the ability to construct a Mesh surface through scripting. -For more information about the ArrayMesh, please see the :ref:`ArrayMesh tutorial `. +For more information about the ArrayMesh, please see the `ArrayMesh tutorial `. MeshDataTool ^^^^^^^^^^^^ @@ -92,14 +92,14 @@ MeshDataTool The MeshDataTool is a resource that converts Mesh data into arrays of vertices, faces, and edges that can be modified at runtime. -For more information about the MeshDataTool, please see the :ref:`MeshDataTool tutorial `. +For more information about the MeshDataTool, please see the `MeshDataTool tutorial `. SurfaceTool ^^^^^^^^^^^ The SurfaceTool allows the creation of Meshes using an OpenGL 1.x immediate mode style interface. -For more information about the SurfaceTool, please see the :ref:`SurfaceTool tutorial `. +For more information about the SurfaceTool, please see the `SurfaceTool tutorial `. ImmediateGeometry ^^^^^^^^^^^^^^^^^ @@ -113,7 +113,7 @@ ImmediateGeometry is useful for prototyping because of its straightforward API, is rebuilt every frame. It is most useful for adding simple geometry for visual debugging (e.g. by drawing lines to visualize physics raycasts etc.). -For more information about ImmediateGeometry, please see the :ref:`ImmediateGeometry tutorial `. +For more information about ImmediateGeometry, please see the `ImmediateGeometry tutorial `. Which one should I use? ----------------------- diff --git a/tutorials/3d/procedural_geometry/meshdatatool.rst b/tutorials/3d/procedural_geometry/meshdatatool.rst index aaceb05..df18570 100644 --- a/tutorials/3d/procedural_geometry/meshdatatool.rst +++ b/tutorials/3d/procedural_geometry/meshdatatool.rst @@ -3,7 +3,7 @@ Using the MeshDataTool ====================== -The :ref:`MeshDataTool ` is not used to generate geometry. But it is helpful for dynamically altering geometry, for example +The `MeshDataTool ` is not used to generate geometry. But it is helpful for dynamically altering geometry, for example if you want to write a script to tessellate, simplify, or deform meshes. The MeshDataTool is not as fast as altering arrays directly using ArrayMesh. However, it provides more information @@ -16,7 +16,7 @@ for certain mesh algorithms. If you do not need this extra information then it m We initialize the MeshDataTool from an ArrayMesh by calling ``create_from_surface()``. If there is already data initialized in the MeshDataTool, calling ``create_from_surface()`` will clear it for you. Alternatively, you can call ``clear()`` yourself before re-using the MeshDataTool. -In the examples below, assume an ArrayMesh called ``mesh`` has already been created. See :ref:`ArrayMesh tutorial ` for an example of mesh generation. +In the examples below, assume an ArrayMesh called ``mesh`` has already been created. See `ArrayMesh tutorial ` for an example of mesh generation. gdscript GDScript @@ -61,7 +61,7 @@ gdscript GDScript ``` These modifications are not done in place on the ArrayMesh. If you are dynamically updating an existing ArrayMesh, -first delete the existing surface before adding a new one using :ref:`commit_to_surface() `: +first delete the existing surface before adding a new one using `commit_to_surface() `: gdscript GDScript @@ -71,7 +71,7 @@ gdscript GDScript ``` Below is a complete example that turns a spherical mesh called ``mesh`` into a randomly deformed blob complete with updated normals and vertex colors. -See :ref:`ArrayMesh tutorial ` for how to generate the base mesh. +See `ArrayMesh tutorial ` for how to generate the base mesh. gdscript GDScript diff --git a/tutorials/3d/procedural_geometry/surfacetool.rst b/tutorials/3d/procedural_geometry/surfacetool.rst index 1e86807..7e6b2d4 100644 --- a/tutorials/3d/procedural_geometry/surfacetool.rst +++ b/tutorials/3d/procedural_geometry/surfacetool.rst @@ -3,8 +3,8 @@ Using the SurfaceTool ===================== -The :ref:`SurfaceTool ` provides a useful interface for constructing geometry. -The interface is similar to the :ref:`ImmediateGeometry ` node. You +The `SurfaceTool ` provides a useful interface for constructing geometry. +The interface is similar to the `ImmediateGeometry ` node. You set each per-vertex attribute (e.g. normal, uv, color) and then when you add a vertex it captures the attributes. @@ -22,8 +22,8 @@ gdscript GDScript st.add_normal() # Normal never added to a vertex. ``` -When finished generating your geometry with the :ref:`SurfaceTool ` -call ``commit()`` to finish generating the mesh. If an :ref:`ArrayMesh ` is passed +When finished generating your geometry with the `SurfaceTool ` +call ``commit()`` to finish generating the mesh. If an `ArrayMesh ` is passed to ``commit()`` then it appends a new surface to the end of the ArrayMesh. While if nothing is passed in, ``commit()`` returns an ArrayMesh. diff --git a/tutorials/3d/reflection_probes.rst b/tutorials/3d/reflection_probes.rst index 8d2ded5..fa3ad71 100644 --- a/tutorials/3d/reflection_probes.rst +++ b/tutorials/3d/reflection_probes.rst @@ -6,7 +6,7 @@ Reflection probes Introduction ------------ -As stated in the :ref:`doc_spatial_material`, objects can show reflected or diffuse light. +As stated in the `doc_spatial_material`, objects can show reflected or diffuse light. Reflection probes are used as a source of reflected and ambient light for objects inside their area of influence. A probe of this type captures the surroundings (as a sort of 360 degrees image), and stores versions diff --git a/tutorials/3d/spatial_material.rst b/tutorials/3d/spatial_material.rst index d2366a7..6b98f1d 100644 --- a/tutorials/3d/spatial_material.rst +++ b/tutorials/3d/spatial_material.rst @@ -360,7 +360,7 @@ Emission ~~~~~~~~ *Emission* specifies how much light is emitted by the material (keep in mind this -does not include light surrounding geometry unless :ref:`doc_gi_probes` are used). +does not include light surrounding geometry unless `doc_gi_probes` are used). This value is added to the resulting final image and is not affected by other lighting in the scene. diff --git a/tutorials/3d/using_gridmaps.rst b/tutorials/3d/using_gridmaps.rst index 05378da..0b3c1b4 100644 --- a/tutorials/3d/using_gridmaps.rst +++ b/tutorials/3d/using_gridmaps.rst @@ -6,10 +6,10 @@ Using GridMaps Introduction ------------ -:ref:`Gridmaps ` are a tool for creating 3D -game levels, similar to the way :ref:`TileMap ` +`Gridmaps ` are a tool for creating 3D +game levels, similar to the way `TileMap ` works in 2D. You start with a predefined collection of 3D meshes (a -:ref:`class_MeshLibrary`) that can be placed on a grid, +`class_MeshLibrary`) that can be placed on a grid, as if you were building a level with an unlimited amount of Lego blocks. Collisions and navigation can also be added to the meshes, just like you @@ -27,14 +27,14 @@ button. Creating a MeshLibrary ---------------------- -To begin, you need a :ref:`class_MeshLibrary`, which is a collection +To begin, you need a `class_MeshLibrary`, which is a collection of individual meshes that can be used in the gridmap. Open the "MeshLibrary_Source.tscn" scene to see an example of how to set up the mesh library. .. image:: img/gridmap_meshlibrary1.png -As you can see, this scene has a :ref:`class_Spatial` node as its root, and -a number of :ref:`class_MeshInstance` node children. +As you can see, this scene has a `class_Spatial` node as its root, and +a number of `class_MeshInstance` node children. If you don't need any physics in your scene, then you're done. However, in most cases you'll want to assign collision bodies to the meshes. @@ -42,8 +42,8 @@ cases you'll want to assign collision bodies to the meshes. Collisions ---------- -You can manually assign a :ref:`class_StaticBody` and -:ref:`class_CollisionShape` to each mesh. Alternatively, you can use the "Mesh" menu +You can manually assign a `class_StaticBody` and +`class_CollisionShape` to each mesh. Alternatively, you can use the "Mesh" menu to automatically create the collision body based on the mesh data. .. image:: img/gridmap_create_body.png @@ -65,11 +65,11 @@ library. Materials set on the node will be ignored. NavigationMeshes ---------------- -Like all mesh instances, MeshLibrary items can be assigned a :ref:`class_NavigationMesh` +Like all mesh instances, MeshLibrary items can be assigned a `class_NavigationMesh` resource, which can be created manually, or baked as described below. To create the NavigationMesh from a MeshLibrary scene export, place a -:ref:`class_NavigationMeshInstance` child node below the main MeshInstance for the GridMap +`class_NavigationMeshInstance` child node below the main MeshInstance for the GridMap item. Add a valid NavigationMesh resource to the NavigationMeshInstance and some source geometry nodes below and bake the NavigationMesh. @@ -133,4 +133,4 @@ the drawing plane higher or lower on its axis. Using GridMap in code --------------------- -See :ref:`class_GridMap` for details on the node's methods and member variables. +See `class_GridMap` for details on the node's methods and member variables. diff --git a/tutorials/3d/using_multi_mesh_instance.rst b/tutorials/3d/using_multi_mesh_instance.rst index f97d85c..e005546 100644 --- a/tutorials/3d/using_multi_mesh_instance.rst +++ b/tutorials/3d/using_multi_mesh_instance.rst @@ -6,13 +6,13 @@ Using MultiMeshInstance Introduction ~~~~~~~~~~~~ -In a normal scenario, you would use a :ref:`MeshInstance ` +In a normal scenario, you would use a `MeshInstance ` node to display a 3D mesh like a human model for the main character, but in some cases, you would like to create multiple instances of the same mesh in a scene. You *could* duplicate the same node multiple times and adjust the transforms manually. This may be a tedious process and the result may look mechanical. Also, this method is not conducive to rapid iterations. -:ref:`MultiMeshInstance ` is one of the possible +`MultiMeshInstance ` is one of the possible solutions to this problem. MultiMeshInstance, as the name suggests, creates multiple copies of a @@ -31,7 +31,7 @@ on. In the tree example, this would be the landscape. The other node is used as the source, the mesh that you want to have duplicated. In the tree case, this would be the tree itself. -In our example, we would use a :ref:`Spatial ` node as the root node of +In our example, we would use a `Spatial ` node as the root node of the scene. Your scene tree would look like this: .. image:: img/multimesh_scene_tree.png diff --git a/tutorials/3d/using_transforms.rst b/tutorials/3d/using_transforms.rst index ec2c038..d858394 100644 --- a/tutorials/3d/using_transforms.rst +++ b/tutorials/3d/using_transforms.rst @@ -79,18 +79,18 @@ There are a few reasons this may happen: Say no to Euler angles ====================== -The result of all this is that you should **not use** the ``rotation`` property of :ref:`class_Spatial` nodes in Godot for games. It's there to be used mainly in the editor, for coherence with the 2D engine, and for simple rotations (generally just one axis, or even two in limited cases). As much as you may be tempted, don't use it. +The result of all this is that you should **not use** the ``rotation`` property of `class_Spatial` nodes in Godot for games. It's there to be used mainly in the editor, for coherence with the 2D engine, and for simple rotations (generally just one axis, or even two in limited cases). As much as you may be tempted, don't use it. Instead, there is a better way to solve your rotation problems. Introducing transforms ---------------------- -Godot uses the :ref:`class_Transform` datatype for orientations. Each :ref:`class_Spatial` node contains a ``transform`` property which is relative to the parent's transform, if the parent is a Spatial-derived type. +Godot uses the `class_Transform` datatype for orientations. Each `class_Spatial` node contains a ``transform`` property which is relative to the parent's transform, if the parent is a Spatial-derived type. It is also possible to access the world coordinate transform via the ``global_transform`` property. -A transform has a :ref:`class_Basis` (transform.basis sub-property), which consists of three :ref:`class_Vector3` vectors. These are accessed via the ``transform.basis`` property and can be accessed directly by ``transform.basis.x``, ``transform.basis.y``, and ``transform.basis.z``. Each vector points in the direction its axis has been rotated, so they effectively describe the node's total rotation. The scale (as long as it's uniform) can also be inferred from the length of the axes. A *basis* can also be interpreted as a 3x3 matrix and used as ``transform.basis[x][y]``. +A transform has a `class_Basis` (transform.basis sub-property), which consists of three `class_Vector3` vectors. These are accessed via the ``transform.basis`` property and can be accessed directly by ``transform.basis.x``, ``transform.basis.y``, and ``transform.basis.z``. Each vector points in the direction its axis has been rotated, so they effectively describe the node's total rotation. The scale (as long as it's uniform) can also be inferred from the length of the axes. A *basis* can also be interpreted as a 3x3 matrix and used as ``transform.basis[x][y]``. A default basis (unmodified) is akin to: @@ -121,7 +121,7 @@ The gizmo's arrows show the ``X``, ``Y``, and ``Z`` axes (in red, green, and blu .. image:: img/transforms_gizmo.png -For more information on the mathematics of vectors and transforms, please read the :ref:`doc_vector_math` tutorials. +For more information on the mathematics of vectors and transforms, please read the `doc_vector_math` tutorials. Manipulating transforms ======================= @@ -203,7 +203,7 @@ gdscript GDScript bullet.speed = transform.basis.z * BULLET_SPEED ``` -Is the enemy looking at the player? Use the dot product for this (see the :ref:`doc_vector_math` tutorial for an explanation of the dot product): +Is the enemy looking at the player? Use the dot product for this (see the `doc_vector_math` tutorial for an explanation of the dot product): gdscript GDScript @@ -285,7 +285,7 @@ gdscript GDScript transform.basis = Basis(c) ``` -The :ref:`class_Quat` type reference has more information on the datatype (it +The `class_Quat` type reference has more information on the datatype (it can also do transform accumulation, transform points, etc., though this is used less often). If you interpolate or apply operations to quaternions many times, keep in mind they need to be eventually normalized. Otherwise, they will also diff --git a/tutorials/animation/2d_skeletons.rst b/tutorials/animation/2d_skeletons.rst index 49523a6..2e8bd45 100644 --- a/tutorials/animation/2d_skeletons.rst +++ b/tutorials/animation/2d_skeletons.rst @@ -32,7 +32,7 @@ Setup .. seealso:: Before starting, we recommend you to go through the - :ref:`doc_cutout_animation` tutorial to gain a general understanding of + `doc_cutout_animation` tutorial to gain a general understanding of animating within Godot. For this tutorial, we will be using a single image to construct our character. diff --git a/tutorials/animation/animation_tree.rst b/tutorials/animation/animation_tree.rst index 76cf9da..53da67d 100644 --- a/tutorials/animation/animation_tree.rst +++ b/tutorials/animation/animation_tree.rst @@ -6,13 +6,13 @@ Using AnimationTree Introduction ------------ -With :ref:`AnimationPlayer `, Godot has one of the most flexible animation systems that you can find in any game engine. +With `AnimationPlayer `, Godot has one of the most flexible animation systems that you can find in any game engine. The ability to animate almost any property in any node or resource, as well as having dedicated transform, bezier, function calling, audio and sub-animation tracks, is pretty much unique. However, the support for blending those animations via ``AnimationPlayer`` is relatively limited, as only a fixed cross-fade transition time can be set. -:ref:`AnimationTree ` is a new node introduced in Godot 3.1 to deal with advanced transitions. +`AnimationTree ` is a new node introduced in Godot 3.1 to deal with advanced transitions. It supersedes the ancient ``AnimationTreePlayer``, while adding a huge amount of features and flexibility. Creating an AnimationTree @@ -193,7 +193,7 @@ transformation visually (the animation will stay in place). .. image:: img/animtree14.png -Afterwards, the actual motion can be retrieved via the :ref:`AnimationTree ` API as a transform: +Afterwards, the actual motion can be retrieved via the `AnimationTree ` API as a transform: gdscript GDScript @@ -201,7 +201,7 @@ gdscript GDScript anim_tree.get_root_motion_transform() ``` -This can be fed to functions such as :ref:`KinematicBody.move_and_slide ` to control the character movement. +This can be fed to functions such as `KinematicBody.move_and_slide ` to control the character movement. There is also a tool node, ``RootMotionView``, that can be placed in a scene and will act as a custom floor for your character and animations (this node is disabled by default during the game). @@ -250,7 +250,7 @@ current state to another one, while visiting all the intermediate ones. This is In the absence of any viable set of transitions starting at the current state and finishing at the destination state, the graph teleports to the destination state. -To use the travel ability, you should first retrieve the :ref:`AnimationNodeStateMachinePlayback ` +To use the travel ability, you should first retrieve the `AnimationNodeStateMachinePlayback ` object from the ``AnimationTree`` node (it is exported as a property). diff --git a/tutorials/animation/cutout_animation.rst b/tutorials/animation/cutout_animation.rst index 4fd3cb1..ed7a18f 100644 --- a/tutorials/animation/cutout_animation.rst +++ b/tutorials/animation/cutout_animation.rst @@ -39,7 +39,7 @@ Godot provides tools for working with cutout rigs, and is ideal for the workflow selectively for complex parts such as hands, feet, changing facial expressions, etc. - **Custom Shaped Elements**: Custom shapes can be created with - :ref:`Polygon2D ` + `Polygon2D ` allowing UV animation, deformations, etc. - **Particle Systems**: A cutout animation rig can be combined with particle systems. This can be useful for magic effects, jetpacks, etc. @@ -87,7 +87,7 @@ and dragging with the left mouse button. To exit rotate mode hit :kbd:`ESC`. The rotation pivot is wrong and needs to be adjusted. -This small cross in the middle of the :ref:`Sprite ` is +This small cross in the middle of the `Sprite ` is the rotation pivot: .. image:: img/tuto_cutout4.png @@ -130,7 +130,7 @@ of the torso. We'll fix this problem with ``RemoteTransform2D`` nodes. RemoteTransform2D node ~~~~~~~~~~~~~~~~~~~~~~ -The :ref:`RemoteTransform2D ` node transforms nodes +The `RemoteTransform2D ` node transforms nodes somewhere else in the hierarchy. This node applies its own transform (including any transformation it inherits from its parents) to the remote node it targets. @@ -193,7 +193,7 @@ node with its parent. And there's currently no child of the hand node. With this knowledge let's try again. The first step is creating an endpoint node. Any kind of node will do, -but :ref:`Position2D ` is preferred because it's +but `Position2D ` is preferred because it's visible in the editor. The endpoint node will ensure that the last bone has orientation. @@ -265,7 +265,7 @@ Animation tips The following section will be a collection of tips for creating animation for your cutout rigs. For more information on how the animation system in Godot -works, see :ref:`doc_introduction_animation`. +works, see `doc_introduction_animation`. Setting keyframes and excluding properties ------------------------------------------ @@ -368,4 +368,4 @@ To apply the same easing curve to multiple keyframes at once: Skeletal deform can be used to augment a cutout rig, allowing single pieces to deform organically (e.g. antennae that wobble as an insect character walks). -This process is described in a :ref:`separate tutorial `. +This process is described in a `separate tutorial `. diff --git a/tutorials/animation/introduction.rst b/tutorials/animation/introduction.rst index faaa878..55a3638 100644 --- a/tutorials/animation/introduction.rst +++ b/tutorials/animation/introduction.rst @@ -3,7 +3,7 @@ Introduction to the animation features ====================================== -The :ref:`class_AnimationPlayer` node allows you to create anything +The `class_AnimationPlayer` node allows you to create anything from simple to complex animations. In this guide you learn to: @@ -22,7 +22,7 @@ Create an AnimationPlayer node ------------------------------ To use the animation tools we first have to create an -:ref:`class_AnimationPlayer` node. +`class_AnimationPlayer` node. The AnimationPlayer node type is the data container for your animations. One AnimationPlayer node can hold multiple animations, that can @@ -233,7 +233,7 @@ values. This can be: - **Discrete:** Only update the property on keyframes. - **Trigger:** Only update the property on keyframes or triggers. Triggers are a type of keyframe used by the - ``current_animation`` property of a :ref:`class_AnimationPlayer`, + ``current_animation`` property of a `class_AnimationPlayer`, and Animation Playback tracks. - **Capture:** If the first keyframe's time is greater than ``0.0``, the current value of the property will be remembered and @@ -323,11 +323,11 @@ Advanced: Call Method tracks Godot's animation engine doesn't stop here. If you're already comfortable with Godot's scripting language -:ref:`doc_gdscript` and :doc:`/classes/index` you +`doc_gdscript` and :doc:`/classes/index` you know that each node type is a class and has a bunch of callable methods. -For example, the :ref:`class_AudioStreamPlayer` node type has a +For example, the `class_AudioStreamPlayer` node type has a method to play an audio stream. Wouldn't it be great to use a method at a specific keyframe in an @@ -340,7 +340,7 @@ To demonstrate, we're going to use a call method track to play audio at a specific keyframe. Normally to play audio you should use an audio track, but for the sake of demonstrating methods we're going to do it this way. -Add a :ref:`class_AudioStreamPlayer` to the Scene Tree and setup a +Add a `class_AudioStreamPlayer` to the Scene Tree and setup a stream using an audio file you put in your project. Click on "Add track" (|Add track|) on the animation panel's track @@ -353,7 +353,7 @@ Select "Add Call Method Track" from the list of possible track types. Add Call Method Track -Select the :ref:`class_AudioStreamPlayer` node in the selection +Select the `class_AudioStreamPlayer` node in the selection window. Godot adds the track with the reference to the node. .. figure:: img/animation_select_audiostreamplayer.png @@ -369,7 +369,7 @@ one. .. image:: img/animation_method_options.png When Godot reaches the keyframe, Godot calls the -:ref:`class_AudioStreamPlayer` node's "play" function and the stream +`class_AudioStreamPlayer` node's "play" function and the stream plays. You can change its position by dragging it on the timeline, you can also diff --git a/tutorials/animation/playing_videos.rst b/tutorials/animation/playing_videos.rst index 304202b..f05a27a 100644 --- a/tutorials/animation/playing_videos.rst +++ b/tutorials/animation/playing_videos.rst @@ -3,7 +3,7 @@ Playing videos ============== -Godot supports video playback with the :ref:`class_VideoPlayer` node. +Godot supports video playback with the `class_VideoPlayer` node. Supported playback formats -------------------------- @@ -38,7 +38,7 @@ Setting up VideoPlayer and load an ``.ogv`` file in the Stream property. - If you don't have your video in Ogg Theora format yet, jump to - :ref:`doc_playing_videos_recommended_theora_encoding_settings`. + `doc_playing_videos_recommended_theora_encoding_settings`. 3. If you want the video to play as soon as the scene is loaded, check **Autoplay** in the inspector. If not, leave **Autoplay** disabled and call @@ -49,7 +49,7 @@ Handling resizing and different aspect ratios ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ By default in Godot 4.0, the VideoPlayer will automatically be resized to match -the video's resolution. You can make it follow usual :ref:`class_Control` sizing +the video's resolution. You can make it follow usual `class_Control` sizing by enabling **Expand** on the VideoPlayer node. To adjust how the VideoPlayer node resizes depending on window size, @@ -57,7 +57,7 @@ adjust the anchors using the **Layout** menu at the top of the 2D editor viewport. However, this setup may not be powerful enough to handle all use cases, such as playing fullscreen videos without distorting the video (but with empty space on the edges instead). For more control, you can use an -:ref:`class_AspectRatioContainer` node, which is designed to handle this kind of +`class_AspectRatioContainer` node, which is designed to handle this kind of use case: Add an AspectRatioContainer node. Make sure it is not a child of any other @@ -81,20 +81,20 @@ to fit the whole screen while avoiding distortion. .. seealso:: - See :ref:`doc_multiple_resolutions` for more tips on supporting multiple + See `doc_multiple_resolutions` for more tips on supporting multiple aspect ratios in your project. Displaying a video on a 3D surface ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Using a VideoPlayer node as a child of a :ref:`class_Viewport` node, +Using a VideoPlayer node as a child of a `class_Viewport` node, it's possible to display any 2D node on a 3D surface. For example, this can be used to display animated billboards when frame-by-frame animation would require too much memory. This can be done with the following steps: -1. Create a :ref:`class_Viewport` node. Set its size to match your video's size +1. Create a `class_Viewport` node. Set its size to match your video's size in pixels. 2. Create a VideoPlayer node *as a child of the Viewport node* and specify a video path in it. Make sure **Expand** is disabled, and enable **Autoplay** if needed. @@ -112,7 +112,7 @@ This can be done with the following steps: 8. If the billboard is supposed to emit its own light, enable **Flags > Unshaded** to improve rendering performance. -See :ref:`doc_viewports` and the +See `doc_viewports` and the `GUI in 3D demo `__ for more information on setting this up. @@ -142,9 +142,9 @@ There are several limitations with the current implementation of video playback - Seeking a video to a certain point is not supported. - Changing playback speed is not supported. VideoPlayer also won't follow - :ref:`Engine.time_scale`. + `Engine.time_scale`. - Looping is not supported, but you can connect a VideoPlayer's - :ref:`finished ` signal to a function + `finished ` signal to a function that plays the video again. However, this will cause a black frame to be visible when the video restarts. This can be worked around by adding a fade to black in the video file before the video ends, or by hiding the video for one diff --git a/tutorials/assets_pipeline/import_process.rst b/tutorials/assets_pipeline/import_process.rst index 4291de2..e0c49ad 100644 --- a/tutorials/assets_pipeline/import_process.rst +++ b/tutorials/assets_pipeline/import_process.rst @@ -18,13 +18,13 @@ Godot will automatically import these files internally and keep the imported resources hidden in a ``res://.import`` folder. This means that when trying to access imported assets through code you -need to use the :ref:`Resource Loader` as it will +need to use the `Resource Loader` as it will automatically take into account where the internal files are saved. If you -try and access an imported asset using the :ref:`File ` class +try and access an imported asset using the `File ` class it will work in the editor, but break in the exported project. -However, the :ref:`Resource Loader` cannot access -non imported files, only the :ref:`File ` class can. +However, the `Resource Loader` cannot access +non imported files, only the `File ` class can. Changing import parameters -------------------------- diff --git a/tutorials/assets_pipeline/importing_audio_samples.rst b/tutorials/assets_pipeline/importing_audio_samples.rst index 5a260ce..918a52e 100644 --- a/tutorials/assets_pipeline/importing_audio_samples.rst +++ b/tutorials/assets_pipeline/importing_audio_samples.rst @@ -49,7 +49,7 @@ for music, speech, and long sound effects. Best practices -------------- -Godot has an :ref:`extensive bus system ` with built-in effects. +Godot has an `extensive bus system ` with built-in effects. This saves SFX artists the need to add reverb to the sound effects, reducing their size greatly and ensuring correct trimming. Say no to SFX with baked reverb! diff --git a/tutorials/assets_pipeline/importing_images.rst b/tutorials/assets_pipeline/importing_images.rst index f0b5519..1de7607 100644 --- a/tutorials/assets_pipeline/importing_images.rst +++ b/tutorials/assets_pipeline/importing_images.rst @@ -211,7 +211,7 @@ A few HDR files are broken and contain sRGB color data. It is advised not to use Invert Color ~~~~~~~~~~~~ -Reverses the image's color. This is useful, for example, to convert a height map generated by external programs to depth map to use with :ref:`doc_spatial_material`. +Reverses the image's color. This is useful, for example, to convert a height map generated by external programs to depth map to use with `doc_spatial_material`. Svg --- diff --git a/tutorials/assets_pipeline/importing_scenes.rst b/tutorials/assets_pipeline/importing_scenes.rst index 563bc3d..91f6fbb 100644 --- a/tutorials/assets_pipeline/importing_scenes.rst +++ b/tutorials/assets_pipeline/importing_scenes.rst @@ -99,7 +99,7 @@ separately. Godot uses PBR (physically based rendering) for its materials, so if textures, they can work in Godot. This includes the `Substance suite `__, `ArmorPaint (open source) `__, and `Material Maker (open source) `__. -.. note:: For more information on Godot's materials, see :ref:`doc_spatial_material`. +.. note:: For more information on Godot's materials, see `doc_spatial_material`. Exporting considerations ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -287,7 +287,7 @@ Whether or not the mesh is used in baked lightmaps. - **Enable:** The mesh is used in baked lightmaps. - **Gen Lightmaps:** The mesh is used in baked lightmaps, and unwraps a second UV layer for lightmaps. -.. note:: For more information on light baking see :ref:`doc_baked_lightmaps`. +.. note:: For more information on light baking see `doc_baked_lightmaps`. External Files ~~~~~~~~~~~~~~ @@ -442,8 +442,8 @@ will create a triangle mesh collision shape, which is a slow, but accurate option for collision detection. This option is usually what you want for level geometry (but see also ``-colonly`` below). -The option ``-convcol`` will create a :ref:`class_convexpolygonshape` instead of -a :ref:`class_concavepolygonshape`. Unlike triangle meshes which can be concave, +The option ``-convcol`` will create a `class_convexpolygonshape` instead of +a `class_concavepolygonshape`. Unlike triangle meshes which can be concave, a convex shape can only accurately represent a shape that doesn't have any concave angles (a pyramid is convex, but a hollow box is concave). Due to this, convex collision shapes are generally not suited for level geometry. When @@ -456,22 +456,22 @@ enough for collisions. This can create physics glitches and slow down the engine unnecessarily. To solve this, the ``-colonly`` modifier exists. It will remove the mesh upon -importing and will create a :ref:`class_staticbody` collision instead. +importing and will create a `class_staticbody` collision instead. This helps the visual mesh and actual collision to be separated. -The option ``-convcolonly`` works in a similar way, but will create a :ref:`class_convexpolygonshape` instead. +The option ``-convcolonly`` works in a similar way, but will create a `class_convexpolygonshape` instead. The option ``-colonly`` can also be used with Blender's empty objects. -On import, it will create a :ref:`class_staticbody` with +On import, it will create a `class_staticbody` with a collision node as a child. The collision node will have one of a number of predefined shapes, depending on Blender's empty draw type: .. image:: img/3dimp_BlenderEmptyDrawTypes.png -- Single arrow will create a :ref:`class_rayshape`. -- Cube will create a :ref:`class_boxshape`. -- Image will create a :ref:`class_planeshape`. -- Sphere (and the others not listed) will create a :ref:`class_sphereshape`. +- Single arrow will create a `class_rayshape`. +- Cube will create a `class_boxshape`. +- Image will create a `class_planeshape`. +- Sphere (and the others not listed) will create a `class_sphereshape`. When possible, **try to use a few primitive collision shapes** instead of triangle mesh or convex shapes. Primitive shapes often have the best performance and @@ -485,7 +485,7 @@ reliability. .. seealso:: - See :ref:`doc_collision_shapes_3d` for a comprehensive overview of collision + See `doc_collision_shapes_3d` for a comprehensive overview of collision shapes. Create navigation (-navmesh) @@ -498,18 +498,18 @@ Create a VehicleBody (-vehicle) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A mesh node with the ``-vehicle`` suffix will be imported as a child to a -:ref:`class_VehicleBody` node. +`class_VehicleBody` node. Create a VehicleWheel (-wheel) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A mesh node with the ``-wheel`` suffix will be imported as a child to a -:ref:`class_VehicleWheel` node. +`class_VehicleWheel` node. Rigid Body (-rigid) ~~~~~~~~~~~~~~~~~~~ -A mesh node with the ``-rigid`` suffix will be imported as a :ref:`class_RigidBody`. +A mesh node with the ``-rigid`` suffix will be imported as a `class_RigidBody`. Animation loop (-loop, -cycle) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/tutorials/assets_pipeline/importing_translations.rst b/tutorials/assets_pipeline/importing_translations.rst index 0e90a08..7c17f8b 100644 --- a/tutorials/assets_pipeline/importing_translations.rst +++ b/tutorials/assets_pipeline/importing_translations.rst @@ -31,7 +31,7 @@ or a string with a number (it's just a unique string anyway). .. note:: If you need a more powerful file format, Godot also supports loading translations written in the gettext ``.po`` format. See - :ref:`doc_localization_using_gettext` for details. + `doc_localization_using_gettext` for details. Translation format ------------------ @@ -63,7 +63,7 @@ CSV files must be formatted as follows: | KEYN | string | string | string | +--------+----------+----------+----------+ -The "lang" tags must represent a language, which must be one of the :ref:`valid +The "lang" tags must represent a language, which must be one of the `valid locales ` supported by the engine. The "KEY" tags must be unique and represent a string universally (they are usually in uppercase, to differentiate from other strings). These keys will be replaced at diff --git a/tutorials/audio/audio_buses.rst b/tutorials/audio/audio_buses.rst index a529024..878770c 100644 --- a/tutorials/audio/audio_buses.rst +++ b/tutorials/audio/audio_buses.rst @@ -81,7 +81,7 @@ Finally, toggle the **Playing** property to **On** and sound will flow. .. seealso:: - You may also be interested in reading about :ref:`doc_audio_streams` now. + You may also be interested in reading about `doc_audio_streams` now. Adding effects -------------- @@ -151,7 +151,7 @@ The compressor has many uses. For example: If your goal is to prevent a signal from exceeding a given amplitude altogether, rather than to reduce the dynamic range of the signal, - a :ref:`limiter ` is likely a better choice + a `limiter ` is likely a better choice than a compressor. @@ -258,8 +258,8 @@ Reverb Reverb simulates rooms of different sizes. It has adjustable parameters that can be tweaked to obtain the sound of a specific room. Reverb is commonly outputted -from :ref:`Areas ` -(see :ref:`Reverb buses `), or to apply +from `Areas ` +(see `Reverb buses `), or to apply a "chamber" feel to all sounds. SpectrumAnalyzer diff --git a/tutorials/audio/audio_streams.rst b/tutorials/audio/audio_streams.rst index fe33267..3b350ee 100644 --- a/tutorials/audio/audio_streams.rst +++ b/tutorials/audio/audio_streams.rst @@ -6,7 +6,7 @@ Audio streams Introduction ------------ -As you might have already read in :ref:`doc_audio_buses`, sound is sent to +As you might have already read in `doc_audio_buses`, sound is sent to each bus via an AudioStreamPlayer node. There are different kinds of AudioStreamPlayers. Each one loads an AudioStream and plays it back. @@ -16,7 +16,7 @@ AudioStream An audio stream is an abstract object that emits sound. The sound can come from many places, but is most commonly loaded from the filesystem. Audio files can be loaded as AudioStreams and placed inside an AudioStreamPlayer. You can find -information on supported formats and differences in :ref:`doc_importing_audio_samples`. +information on supported formats and differences in `doc_importing_audio_samples`. There are other types of AudioStreams, such as AudioStreamRandomPitch. This one makes a random adjustment to the sound's pitch every time it's diff --git a/tutorials/audio/recording_with_microphone.rst b/tutorials/audio/recording_with_microphone.rst index 807ec46..e567ac8 100644 --- a/tutorials/audio/recording_with_microphone.rst +++ b/tutorials/audio/recording_with_microphone.rst @@ -41,11 +41,11 @@ gdscript GDScript effect = AudioServer.get_bus_effect(idx, 0) ``` -The audio recording is handled by the :ref:`class_AudioEffectRecord` resource +The audio recording is handled by the `class_AudioEffectRecord` resource which has three methods: -:ref:`get_recording() `, -:ref:`is_recording_active() `, -and :ref:`set_recording_active() `. +`get_recording() `, +`is_recording_active() `, +and `set_recording_active() `. gdscript GDScript diff --git a/tutorials/audio/sync_with_audio.rst b/tutorials/audio/sync_with_audio.rst index 7f82b47..1ec6835 100644 --- a/tutorials/audio/sync_with_audio.rst +++ b/tutorials/audio/sync_with_audio.rst @@ -26,11 +26,11 @@ The problem, in the end, is not this slight delay but synchronizing graphics and Using the system clock to sync ------------------------------ -As mentioned before, If you call :ref:`AudioStreamPlayer.play()`, sound will not begin immediately, but when the audio thread processes the next chunk. +As mentioned before, If you call `AudioStreamPlayer.play()`, sound will not begin immediately, but when the audio thread processes the next chunk. -This delay can't be avoided but it can be estimated by calling :ref:`AudioServer.get_time_to_next_mix()`. +This delay can't be avoided but it can be estimated by calling `AudioServer.get_time_to_next_mix()`. -The output latency (what happens after the mix) can also be estimated by calling :ref:`AudioServer.get_output_latency()`. +The output latency (what happens after the mix) can also be estimated by calling `AudioServer.get_output_latency()`. Add these two and it's possible to guess almost exactly when sound or music will begin playing in the speakers during *_process()*: @@ -65,9 +65,9 @@ For a rhythm game where a song begins and ends after a few minutes, this approac Using the sound hardware clock to sync -------------------------------------- -Using :ref:`AudioStreamPlayer.get_playback_position()` to obtain the current position for the song sounds ideal, but it's not that useful as-is. This value will increment in chunks (every time the audio callback mixed a block of sound), so many calls can return the same value. Added to this, the value will be out of sync with the speakers too because of the previously mentioned reasons. +Using `AudioStreamPlayer.get_playback_position()` to obtain the current position for the song sounds ideal, but it's not that useful as-is. This value will increment in chunks (every time the audio callback mixed a block of sound), so many calls can return the same value. Added to this, the value will be out of sync with the speakers too because of the previously mentioned reasons. -To compensate for the "chunked" output, there is a function that can help: :ref:`AudioServer.get_time_since_last_mix()`. +To compensate for the "chunked" output, there is a function that can help: `AudioServer.get_time_since_last_mix()`. Adding the return value from this function to *get_playback_position()* increases precision: diff --git a/tutorials/best_practices/autoloads_versus_internal_nodes.rst b/tutorials/best_practices/autoloads_versus_internal_nodes.rst index 5c4b56e..828e48e 100644 --- a/tutorials/best_practices/autoloads_versus_internal_nodes.rst +++ b/tutorials/best_practices/autoloads_versus_internal_nodes.rst @@ -5,8 +5,8 @@ Autoloads versus regular nodes Godot offers a feature to automatically load nodes at the root of your project, allowing you to access them globally, that can fulfill the role of a Singleton: -:ref:`doc_singletons_autoload`. These auto-loaded nodes are not freed when you -change the scene from code with :ref:`SceneTree.change_scene `. +`doc_singletons_autoload`. These auto-loaded nodes are not freed when you +change the scene from code with `SceneTree.change_scene `. In this guide, you will learn when to use the Autoload feature, and techniques you can use to avoid it. @@ -19,7 +19,7 @@ organize a lot of functionality into a globally accessible object. Godot offers many ways to avoid global state thanks to the node tree and signals. For example, let's say we are building a platformer and want to collect coins -that play a sound effect. There's a node for that: the :ref:`AudioStreamPlayer +that play a sound effect. There's a node for that: the `AudioStreamPlayer `. But if we call the ``AudioStreamPlayer`` while it is already playing a sound, the new sound interrupts the first. @@ -67,12 +67,12 @@ Another reason to use an Autoload can be that you want to reuse the same method or data across many scenes. In the case of functions, you can create a new type of ``Node`` that provides -that feature for an individual scene using the :ref:`class_name +that feature for an individual scene using the `class_name ` keyword in GDScript. When it comes to data, you can either: -1. Create a new type of :ref:`Resource ` to share the data. +1. Create a new type of `Resource ` to share the data. 2. Store the data in an object to which each node has access, for example using the ``owner`` property to access the scene's root node. diff --git a/tutorials/best_practices/data_preferences.rst b/tutorials/best_practices/data_preferences.rst index d135222..6ad1c9b 100644 --- a/tutorials/best_practices/data_preferences.rst +++ b/tutorials/best_practices/data_preferences.rst @@ -42,8 +42,8 @@ Array vs. Dictionary vs. Object Godot stores all variables in the scripting API in the `Variant `_ class. Variants can store Variant-compatible data structures such as -:ref:`Array ` and :ref:`Dictionary ` as well as -:ref:`Object ` s. +`Array ` and `Dictionary ` as well as +`Object ` s. Godot implements Array as a ``Vector``. The engine stores the Array contents in a contiguous section of memory, i.e. they are in a row adjacent @@ -54,7 +54,7 @@ to each other. array object in traditional C++ libraries. It is a "templated" type, meaning that its records can only contain a particular type (denoted by angled brackets). So, for example, a - :ref:`PoolStringArray ` would be something like + `PoolStringArray ` would be something like a ``Vector``. Contiguous memory stores imply the following operation performance: @@ -167,9 +167,9 @@ do not. An overview of their operational details is as follows: Godot implements Objects as stupid, but dynamic containers of data content. Objects query data sources when posed questions. For example, to answer the question, "do you have a property called, 'position'?", it might ask -its :ref:`script ` or the :ref:`ClassDB `. +its `script ` or the `ClassDB `. One can find more information about what objects are and how they work in -the :ref:`doc_what_are_godot_classes` article. +the `doc_what_are_godot_classes` article. The important detail here is the complexity of the Object's task. Every time it performs one of these multi-source queries, it runs through *several* @@ -283,7 +283,7 @@ AnimatedTexture vs. AnimatedSprite vs. AnimationPlayer vs. AnimationTree Under what circumstances should one use each of Godot's animation classes? The answer may not be immediately clear to new Godot users. -:ref:`AnimatedTexture ` is a texture that +`AnimatedTexture ` is a texture that the engine draws as an animated loop rather than a static image. Users can manipulate... @@ -291,21 +291,21 @@ Users can manipulate... 2. the number of regions contained within the texture (frames). -Godot's :ref:`VisualServer ` then draws +Godot's `VisualServer ` then draws the regions in sequence at the prescribed rate. The good news is that this involves no extra logic on the part of the engine. The bad news is that users have very little control. -Also note that AnimatedTexture is a :ref:`Resource ` unlike -the other :ref:`Node ` objects discussed here. One might create -a :ref:`Sprite ` node that uses AnimatedTexture as its texture. +Also note that AnimatedTexture is a `Resource ` unlike +the other `Node ` objects discussed here. One might create +a `Sprite ` node that uses AnimatedTexture as its texture. Or (something the others can't do) one could add AnimatedTextures as tiles -in a :ref:`TileSet ` and integrate it with a -:ref:`TileMap ` for many auto-animating backgrounds that +in a `TileSet ` and integrate it with a +`TileMap ` for many auto-animating backgrounds that all render in a single batched draw call. The AnimatedSprite node, in combination with the -:ref:`SpriteFrames ` resource, allows one to create a +`SpriteFrames ` resource, allows one to create a variety of animation sequences through spritesheets, flip between animations, and control their speed, regional offset, and orientation. This makes them well-suited to controlling 2D frame-based animations. @@ -313,7 +313,7 @@ well-suited to controlling 2D frame-based animations. If one needs trigger other effects in relation to animation changes (for example, create particle effects, call functions, or manipulate other peripheral elements besides the frame-based animation), then will need to use -an :ref:`AnimationPlayer ` node in conjunction with +an `AnimationPlayer ` node in conjunction with the AnimatedSprite. AnimationPlayers are also the tool one will need to use if they wish to design @@ -332,6 +332,6 @@ While one needs an AnimationPlayer to design each of the individual animation sequences for a game, it can also be useful to combine animations for blending, i.e. enabling smooth transitions between these animations. There may also be a hierarchical structure between animations that one plans out for -their object. These are the cases where the :ref:`AnimationTree ` +their object. These are the cases where the `AnimationTree ` shines. One can find an in-depth guide on using the AnimationTree -:ref:`here `. +`here `. diff --git a/tutorials/best_practices/godot_interfaces.rst b/tutorials/best_practices/godot_interfaces.rst index fd36da8..693e70a 100644 --- a/tutorials/best_practices/godot_interfaces.rst +++ b/tutorials/best_practices/godot_interfaces.rst @@ -15,7 +15,7 @@ The rest of this tutorial outlines the various ways of doing all this. Acquiring object references --------------------------- -For all :ref:`Object `\s, the most basic way of referencing them +For all `Object `\s, the most basic way of referencing them is to get a reference to an existing object from another acquired instance. gdscript GDScript @@ -25,9 +25,9 @@ gdscript GDScript var obj = node.get_object() # Method access. ``` -The same principle applies for :ref:`Reference ` objects. -While users often access :ref:`Node ` and -:ref:`Resource ` this way, alternative measures are available. +The same principle applies for `Reference ` objects. +While users often access `Node ` and +`Resource ` this way, alternative measures are available. Instead of property or method access, one can get Resources by load access. @@ -72,7 +72,7 @@ Note the following: 3. Keep in mind that loading a resource fetches the cached resource instance maintained by the engine. To get a new object, one must - :ref:`duplicate ` an existing reference + `duplicate ` an existing reference or instantiate one from scratch with ``new()``. Nodes likewise have an alternative access point: the SceneTree. @@ -140,10 +140,10 @@ Godot's scripting API is duck-typed. This means that if a script executes an operation, Godot doesn't validate that it supports the operation by **type**. It instead checks that the object **implements** the individual method. -For example, the :ref:`CanvasItem ` class has a ``visible`` +For example, the `CanvasItem ` class has a ``visible`` property. All properties exposed to the scripting API are in fact a setter and getter pair bound to a name. If one tried to access -:ref:`CanvasItem.visible `, then Godot would do the +`CanvasItem.visible `, then Godot would do the following checks, in order: - If the object has a script attached, it will attempt to set the property @@ -155,7 +155,7 @@ following checks, in order: the ClassDB for the "visible" property against the CanvasItem class and all of its inherited types. If found, it will call the bound setter or getter. For more information about HashMaps, see the - :ref:`data preferences ` docs. + `data preferences ` docs. - If not found, it does an explicit check to see if the user wants to access the "script" or "meta" properties. @@ -166,9 +166,9 @@ following checks, in order: is also the case with the ``_get_property_list`` method. - Note that this happens even for non-legal symbol names such as in the - case of :ref:`TileSet `'s "1/tile_name" property. This + case of `TileSet `'s "1/tile_name" property. This refers to the name of the tile with ID 1, i.e. - :ref:`TileSet.tile_get_name(1) `. + `TileSet.tile_get_name(1) `. As a result, this duck-typed system can locate a property either in the script, the object's class, or any class that object inherits, but only for things @@ -199,7 +199,7 @@ gdscript GDScript ``` - A method check. In the case of - :ref:`CanvasItem.visible `, one can + `CanvasItem.visible `, one can access the methods, ``set_visible`` and ``is_visible`` like any other method. gdscript GDScript @@ -262,7 +262,7 @@ gdscript GDScript # group can fill in for it. ``` -- Outsource the access to a :ref:`FuncRef `. These may be useful +- Outsource the access to a `FuncRef `. These may be useful in cases where one needs the max level of freedom from dependencies. In this case, one relies on an external context to setup the method. diff --git a/tutorials/best_practices/godot_notifications.rst b/tutorials/best_practices/godot_notifications.rst index 6c72763..10a7115 100644 --- a/tutorials/best_practices/godot_notifications.rst +++ b/tutorials/best_practices/godot_notifications.rst @@ -4,10 +4,10 @@ Godot notifications =================== Every Object in Godot implements a -:ref:`_notification ` method. Its purpose is to +`_notification ` method. Its purpose is to allow the Object to respond to a variety of engine-level callbacks that may relate to it. For example, if the engine tells a -:ref:`CanvasItem ` to "draw", it will call +`CanvasItem ` to "draw", it will call ``_notification(NOTIFICATION_DRAW)``. Some of these notifications, like draw, are useful to override in scripts. So @@ -28,28 +28,28 @@ much so that Godot exposes many of them with dedicated functions: What users might *not* realize is that notifications exist for types other than Node alone: -- :ref:`Object::NOTIFICATION_POSTINITIALIZE `: +- `Object::NOTIFICATION_POSTINITIALIZE `: a callback that triggers during object initialization. Not accessible to scripts. -- :ref:`Object::NOTIFICATION_PREDELETE `: +- `Object::NOTIFICATION_PREDELETE `: a callback that triggers before the engine deletes an Object, i.e. a 'destructor'. -- :ref:`MainLoop::NOTIFICATION_WM_MOUSE_ENTER `: +- `MainLoop::NOTIFICATION_WM_MOUSE_ENTER `: a callback that triggers when the mouse enters the window in the operating system that displays the game content. And many of the callbacks that *do* exist in Nodes don't have any dedicated methods, but are still quite useful. -- :ref:`Node::NOTIFICATION_PARENTED `: +- `Node::NOTIFICATION_PARENTED `: a callback that triggers anytime one adds a child node to another node. -- :ref:`Node::NOTIFICATION_UNPARENTED `: +- `Node::NOTIFICATION_UNPARENTED `: a callback that triggers anytime one removes a child node from another node. -- :ref:`Popup::NOTIFICATION_POST_POPUP `: +- `Popup::NOTIFICATION_POST_POPUP `: a callback that triggers after a Popup node completes any ``popup*`` method. Note the difference from its ``about_to_show`` signal which triggers *before* its appearance. @@ -62,7 +62,7 @@ One can access all these custom notifications from the universal overridden by scripts. A classic example is the - :ref:`_init ` method in Object. While it has no + `_init ` method in Object. While it has no ``NOTIFICATION_*`` equivalent, the engine still calls the method. Most languages (except C#) rely on it as a constructor. @@ -186,7 +186,7 @@ to the SceneTree, the ``_enter_tree`` and ``_ready`` calls occur. If one needs to trigger behavior that occurs as nodes parent to another, regardless of whether it occurs as part of the main/active scene or not, one -can use the :ref:`PARENTED ` notification. +can use the `PARENTED ` notification. For example, here is a snippet that connects a node's method to a custom signal on the parent node without failing. Useful on data-centric nodes that one might create at runtime. diff --git a/tutorials/best_practices/introduction_best_practices.rst b/tutorials/best_practices/introduction_best_practices.rst index 349ec01..14a44d6 100644 --- a/tutorials/best_practices/introduction_best_practices.rst +++ b/tutorials/best_practices/introduction_best_practices.rst @@ -17,7 +17,7 @@ That is why each article starts from a real-world problem. We will break down each problem in fundamental questions, suggest solutions, analyze the pros and cons of each option, and highlight the best course of action for the problem at hand. -You should start by reading :ref:`doc_what_are_godot_classes`. It explains how +You should start by reading `doc_what_are_godot_classes`. It explains how Godot's nodes and scenes relate to classes and objects in other Object-Oriented programming languages. It will help you make sense of the rest of the series. diff --git a/tutorials/best_practices/logic_preferences.rst b/tutorials/best_practices/logic_preferences.rst index c50547a..b63ce0c 100644 --- a/tutorials/best_practices/logic_preferences.rst +++ b/tutorials/best_practices/logic_preferences.rst @@ -10,15 +10,15 @@ Loading vs. preloading ---------------------- In GDScript, there exists the global -:ref:`preload ` method. It loads resources as +`preload ` method. It loads resources as early as possible to front-load the "loading" operations and avoid loading resources while in the middle of performance-sensitive code. -Its counterpart, the :ref:`load ` method, loads a +Its counterpart, the `load ` method, loads a resource only when it reaches the load statement. That is, it will load a resource in-place which can cause slowdowns when it occurs in the middle of sensitive processes. The ``load`` function is also an alias for -:ref:`ResourceLoader.load(path) ` which is +`ResourceLoader.load(path) ` which is accessible to *all* scripting languages. So, when exactly does preloading occur versus loading, and when should one use @@ -95,7 +95,7 @@ consider: would be to unload the entire script. If they are instead loaded properties, then one can set them to ``null`` and remove all references to the resource entirely (which, as a - :ref:`Reference `-extending type, will cause the + `Reference `-extending type, will cause the resources to delete themselves from memory). Large levels: static vs. dynamic @@ -140,5 +140,5 @@ As such, the best options would be... into a plugin. For an example of the various ways one can swap scenes around at runtime, -please see the :ref:`"Change scenes manually" ` +please see the `"Change scenes manually" ` documentation. diff --git a/tutorials/best_practices/node_alternatives.rst b/tutorials/best_practices/node_alternatives.rst index f896dc1..6c0553a 100644 --- a/tutorials/best_practices/node_alternatives.rst +++ b/tutorials/best_practices/node_alternatives.rst @@ -13,15 +13,15 @@ Godot provides more lightweight objects for creating APIs which nodes use. Be sure to keep these in mind as options when designing how you wish to build your project's features. -1. :ref:`Object `: The ultimate lightweight object, the original +1. `Object `: The ultimate lightweight object, the original Object must use manual memory management. With that said, it isn't too difficult to create one's own custom data structures, even node structures, - that are also lighter than the :ref:`Node ` class. + that are also lighter than the `Node ` class. - - **Example:** See the :ref:`Tree ` node. It supports a high level + - **Example:** See the `Tree ` node. It supports a high level of customization for a table of content with an arbitrary number of rows and columns. The data that it uses to generate its visualization - though is actually a tree of :ref:`TreeItem ` Objects. + though is actually a tree of `TreeItem ` Objects. - **Advantages:** Simplifying one's API to smaller scoped objects helps improve its accessibility and improve iteration time. Rather than working with the @@ -33,27 +33,27 @@ your project's features. For example, if the object's creator decides to delete it out of nowhere, this would trigger an error state when one next accesses it. -2. :ref:`Reference `: Only a little more complex than Object. +2. `Reference `: Only a little more complex than Object. They track references to themselves, only deleting loaded memory when no further references to themselves exist. These are useful in the majority of cases where one needs data in a custom class. - - **Example:** See the :ref:`File ` object. It functions + - **Example:** See the `File ` object. It functions just like a regular Object except that one need not delete it themselves. - **Advantages:** same as the Object. -3. :ref:`Resource `: Only slightly more complex than Reference. +3. `Resource `: Only slightly more complex than Reference. They have the innate ability to serialize/deserialize (i.e. save and load) their object properties to/from Godot resource files. - **Example:** Scripts, PackedScene (for scene files), and other types like - each of the :ref:`AudioEffect ` classes. Each of these + each of the `AudioEffect ` classes. Each of these can be save and loaded, therefore they extend from Resource. - **Advantages:** Much has - :ref:`already been said ` - on :ref:`Resource `'s advantages over traditional data + `already been said ` + on `Resource `'s advantages over traditional data storage methods. In the context of using Resources over Nodes though, their main advantage is in Inspector-compatibility. While nearly as lightweight as Object/Reference, they can still display and export diff --git a/tutorials/best_practices/scene_organization.rst b/tutorials/best_practices/scene_organization.rst index 61264b3..1f6cfc3 100644 --- a/tutorials/best_practices/scene_organization.rst +++ b/tutorials/best_practices/scene_organization.rst @@ -75,7 +75,7 @@ gdscript GDScript call(method_name) # Call parent-defined method (which child must own). ``` -3. Initialize a :ref:`FuncRef ` property. Safer than a method +3. Initialize a `FuncRef ` property. Safer than a method as ownership of the method is unnecessary. Used to start behavior. gdscript GDScript @@ -157,12 +157,12 @@ gdscript GDScript To avoid creating and maintaining such documentation, one converts the dependent node ("child" above) into a tool script that implements - :ref:`_get_configuration_warning() `. + `_get_configuration_warning() `. Returning a non-empty string from it will make the Scene dock generate a warning icon with the string as a tooltip by the node. This is the same icon that appears for nodes such as the - :ref:`Area2D ` node when it has no child - :ref:`CollisionShape2D ` nodes defined. The editor + `Area2D ` node when it has no child + `CollisionShape2D ` nodes defined. The editor then self-documents the scene through the script code. No content duplication via documentation is necessary. @@ -218,7 +218,7 @@ the various menus and widgets the project needs. - Control "GUI" (gui.gd) When changing levels, one can then swap out the children of the "World" node. -:ref:`Changing scenes manually ` gives users full +`Changing scenes manually ` gives users full control over how their game world transitions. The next step is to consider what gameplay systems one's project requires. @@ -228,13 +228,13 @@ If one has a system that... 2. should be globally accessible 3. should exist in isolation -... then one should create an :ref:`autoload 'singleton' node `. +... then one should create an `autoload 'singleton' node `. .. note:: For smaller games, a simpler alternative with less control would be to have a "Game" singleton that simply calls the - :ref:`SceneTree.change_scene() ` method + `SceneTree.change_scene() ` method to swap out the main scene's content. This structure more or less keeps the "World" as the main game node. @@ -246,7 +246,7 @@ If one has a system that... If one has systems that modify other systems' data, one should define those as their own scripts or scenes rather than autoloads. For more information on the reasons, please see the -:ref:`Autoloads versus regular nodes ` +`Autoloads versus regular nodes ` documentation. Each subsystem within one's game should have its own section within the @@ -259,11 +259,11 @@ own place in the hierarchy as a sibling or some other relation. In some cases, one needs these separated nodes to *also* position themselves relative to each other. One can use the - :ref:`RemoteTransform ` / - :ref:`RemoteTransform2D ` nodes for this purpose. + `RemoteTransform ` / + `RemoteTransform2D ` nodes for this purpose. They will allow a target node to conditionally inherit selected transform elements from the Remote\* node. To assign the ``target`` - :ref:`NodePath `, use one of the following: + `NodePath `, use one of the following: 1. A reliable third party, likely a parent node, to mediate the assignment. 2. A group, to easily pull a reference to the desired node (assuming there @@ -307,12 +307,12 @@ own place in the hierarchy as a sibling or some other relation. In contrast, if one ever needs to have a child node that does *not* inherit the transform of their parent, one has the following options: - 1. The **declarative** solution: place a :ref:`Node ` in between + 1. The **declarative** solution: place a `Node ` in between them. As nodes with no transform, Nodes will not pass along such information to their children. 2. The **imperative** solution: Use the ``set_as_toplevel`` setter for the - :ref:`CanvasItem ` or - :ref:`Spatial ` node. This will make + `CanvasItem ` or + `Spatial ` node. This will make the node ignore its inherited transform. .. note:: diff --git a/tutorials/best_practices/scenes_versus_scripts.rst b/tutorials/best_practices/scenes_versus_scripts.rst index 06ed89d..66827c7 100644 --- a/tutorials/best_practices/scenes_versus_scripts.rst +++ b/tutorials/best_practices/scenes_versus_scripts.rst @@ -73,7 +73,7 @@ name. There are two systems for registering types... -- :ref:`Custom Types ` +- `Custom Types ` - Editor-only. Typenames are not accessible at runtime. @@ -88,9 +88,9 @@ There are two systems for registering types... - Works for all scripting languages because it deals with Script resources in abstract. - - Set up using :ref:`EditorPlugin.add_custom_type `. + - Set up using `EditorPlugin.add_custom_type `. -- :ref:`Script Classes ` +- `Script Classes ` - Editor and runtime accessible. @@ -156,7 +156,7 @@ Script code like this is much slower than engine-side C++ code. Each instruction makes a call to the scripting API which leads to many "lookups" on the back-end to find the logic to execute. -Scenes help to avoid this performance issue. :ref:`PackedScene +Scenes help to avoid this performance issue. `PackedScene `, the base type that scenes inherit from, defines resources that use serialized data to create objects. The engine can process scenes in batches on the back-end and provide much better performance than scripts. diff --git a/tutorials/best_practices/what_are_godot_classes.rst b/tutorials/best_practices/what_are_godot_classes.rst index 75ddfcb..cc92309 100644 --- a/tutorials/best_practices/what_are_godot_classes.rst +++ b/tutorials/best_practices/what_are_godot_classes.rst @@ -16,13 +16,13 @@ how they work under the hood. How scripts work in the engine ------------------------------ -The engine provides built-in classes like :ref:`Node `. You can extend those to create +The engine provides built-in classes like `Node `. You can extend those to create derived types using a script. These scripts are not technically classes. Instead, they are resources that tell the engine a sequence of initializations to perform on one of the engine's built-in classes. -Godot's internal classes have methods that register a class's data with a :ref:`ClassDB +Godot's internal classes have methods that register a class's data with a `ClassDB `. This database provides runtime access to class information. ``ClassDB`` contains information about classes like: @@ -35,15 +35,15 @@ This ``ClassDB`` is what objects check against when performing an operation like property or calling a method. It checks the database's records and the object's base types' records to see if the object supports the operation. -Attaching a :ref:`Script ` to your object extends the methods, properties, and signals +Attaching a `Script ` to your object extends the methods, properties, and signals available from the ``ClassDB``. .. note:: Even scripts that don't use the ``extends`` keyword implicitly inherit from the engine's base - :ref:`Reference ` class. As a result, you can instantiate scripts without the + `Reference ` class. As a result, you can instantiate scripts without the ``extends`` keyword from code. Since they extend ``Reference`` though, you cannot attach them to - a :ref:`Node `. + a `Node `. Scenes ------ diff --git a/tutorials/editor/command_line_tutorial.rst b/tutorials/editor/command_line_tutorial.rst index aa88384..e2c39d2 100644 --- a/tutorials/editor/command_line_tutorial.rst +++ b/tutorials/editor/command_line_tutorial.rst @@ -46,13 +46,13 @@ Command line reference +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Command | Description | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``-e``, ``--editor`` | Start the editor instead of running the scene (:ref:`tools ` must be enabled). | +| ``-e``, ``--editor`` | Start the editor instead of running the scene (`tools ` must be enabled). | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``-p``, ``--project-manager`` | Start the project manager, even if a project is auto-detected (:ref:`tools ` must be enabled). | +| ``-p``, ``--project-manager`` | Start the project manager, even if a project is auto-detected (`tools ` must be enabled). | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``-q``, ``--quit`` | Quit after the first iteration. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``-l ``, ``--language `` | Use a specific locale ( being a two-letter code). See :ref:`doc_locales` for more details. | +| ``-l ``, ``--language `` | Use a specific locale ( being a two-letter code). See `doc_locales` for more details. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--path `` | Path to a project ( must contain a 'project.godot' file). | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -60,7 +60,7 @@ Command line reference +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--main-pack `` | Path to a pack (.pck) file to load. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--render-thread `` | Render thread mode ('unsafe', 'safe', 'separate'). See :ref:`Thread Model ` for more details. | +| ``--render-thread `` | Render thread mode ('unsafe', 'safe', 'separate'). See `Thread Model ` for more details. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--remote-fs
`` | Remote filesystem (``[:]`` address). | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -97,7 +97,7 @@ Command line reference Debug options are only available in the editor and debug export templates (they require ``debug`` or ``release_debug`` build targets, see - :ref:`doc_introduction_to_the_buildsystem_target` for more details). + `doc_introduction_to_the_buildsystem_target` for more details). +------------------------------+---------------------------------------------------------------------------------------------+ | Command | Description | @@ -136,22 +136,22 @@ Command line reference +----------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--check-only`` | Only parse for errors and quit (use with ``--script``). | +----------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--export `` | Export the project using the given export target. Export only main pack if path ends with .pck or .zip (:ref:`tools ` must be enabled). | +| ``--export `` | Export the project using the given export target. Export only main pack if path ends with .pck or .zip (`tools ` must be enabled). | +----------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--export-debug `` | Like ``--export``, but use debug template (:ref:`tools ` must be enabled). | +| ``--export-debug `` | Like ``--export``, but use debug template (`tools ` must be enabled). | +----------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--doctool `` | Dump the engine API reference to the given in XML format, merging if existing files are found (:ref:`tools ` must be enabled). | +| ``--doctool `` | Dump the engine API reference to the given in XML format, merging if existing files are found (`tools ` must be enabled). | +----------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--no-docbase`` | Disallow dumping the base types (used with ``--doctool``, :ref:`tools ` must be enabled). | +| ``--no-docbase`` | Disallow dumping the base types (used with ``--doctool``, `tools ` must be enabled). | +----------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--build-solutions`` | Build the scripting solutions (e.g. for C# projects, :ref:`tools ` must be enabled). | +| ``--build-solutions`` | Build the scripting solutions (e.g. for C# projects, `tools ` must be enabled). | +----------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--gdnative-generate-json-api`` | Generate JSON dump of the Godot API for GDNative bindings (:ref:`tools ` must be enabled). | +| ``--gdnative-generate-json-api`` | Generate JSON dump of the Godot API for GDNative bindings (`tools ` must be enabled). | +----------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--test `` | Run a unit test. Use ``--help`` first to display the list of tests. (:ref:`tools ` must be enabled). | +| ``--test `` | Run a unit test. Use ``--help`` first to display the list of tests. (`tools ` must be enabled). | +----------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--export-pack `` | Like ``--export``, but only export the game pack for the given preset. The extension determines whether it will be in PCK or ZIP format. | -| | (:ref:`tools ` must be enabled). | +| | (`tools ` must be enabled). | +----------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ Path diff --git a/tutorials/editor/index.rst b/tutorials/editor/index.rst index 3880fdc..a3775fb 100644 --- a/tutorials/editor/index.rst +++ b/tutorials/editor/index.rst @@ -3,7 +3,7 @@ Editor manual In this section, we cover the Godot editor in general, from its interface to using it with the command line. We cover some specific editors' interface in -other sections where appropriate. For example, the :ref:`animation editor +other sections where appropriate. For example, the `animation editor `. .. toctree:: diff --git a/tutorials/editor/managing_editor_features.rst b/tutorials/editor/managing_editor_features.rst index c72160c..3a7302b 100644 --- a/tutorials/editor/managing_editor_features.rst +++ b/tutorials/editor/managing_editor_features.rst @@ -15,7 +15,7 @@ With feature profiles, major features and nodes can be hidden from the editor. This only hides parts of the interface and does not actually remove support for these features, so scenes and scripts relying on those features will still work fine. This also means feature profiles are not an optimization technique. For -information on how to optimize Godot see :ref:`doc_optimization`. +information on how to optimize Godot see `doc_optimization`. Creating a profile ------------------ @@ -46,4 +46,4 @@ editor's **Manage Editor Feature Profiles** window and click import, then select This process is potentially cumbersome however if a large amount of computers need custom profiles. As an alternative, you can enable self-contained mode for Godot, which allows putting all editor configuration in the same folder as the editor binary. -See :ref:`doc_data_paths_self_contained_mode` for details. +See `doc_data_paths_self_contained_mode` for details. diff --git a/tutorials/editor/using_the_web_editor.rst b/tutorials/editor/using_the_web_editor.rst index dd69014..3a27249 100644 --- a/tutorials/editor/using_the_web_editor.rst +++ b/tutorials/editor/using_the_web_editor.rst @@ -10,7 +10,7 @@ you can use to work on new or existing projects. The web editor is in a preliminary stage. While its feature set may be sufficient for educational purposes, it is currently **not recommended for - production work**. See :ref:`doc_using_the_web_editor_limitations` below. + production work**. See `doc_using_the_web_editor_limitations` below. Browser support --------------- diff --git a/tutorials/export/android_custom_build.rst b/tutorials/export/android_custom_build.rst index 57fb27b..537444d 100644 --- a/tutorials/export/android_custom_build.rst +++ b/tutorials/export/android_custom_build.rst @@ -14,7 +14,7 @@ There are some reasons why you may want to do this: * Add external SDKs that build with your project. Configuring the custom build is a fairly straightforward process. But first -you need to follow the steps in :ref:`exporting for android` +you need to follow the steps in `exporting for android` up to **Setting it up in Godot**. After doing that, follow the steps below. Set up the custom build environment @@ -28,7 +28,7 @@ Make sure export templates are downloaded. If not, this menu will help you download them. A Gradle-based Android project will be created under ``res://android/build``. -Editing these files is not needed unless you want to :ref:`create +Editing these files is not needed unless you want to `create your own add-ons`, or you really need to modify the project. diff --git a/tutorials/export/changing_application_icon_for_windows.rst b/tutorials/export/changing_application_icon_for_windows.rst index 12c65cb..078921b 100644 --- a/tutorials/export/changing_application_icon_for_windows.rst +++ b/tutorials/export/changing_application_icon_for_windows.rst @@ -106,7 +106,7 @@ the **Application → Icon** field. .. note:: If rcedit fails to change the icon, you can instead - :ref:`compile your own Windows export templates ` + `compile your own Windows export templates ` with the icon changed. To do so, replace `platform/windows/godot.ico `__ with your own ICO file *before* compiling export templates. diff --git a/tutorials/export/exporting_basics.rst b/tutorials/export/exporting_basics.rst index 23be05c..bdd75ff 100644 --- a/tutorials/export/exporting_basics.rst +++ b/tutorials/export/exporting_basics.rst @@ -17,7 +17,7 @@ variety of platforms. First, however, we need to make some changes to the way the game works. .. note:: If you haven't made "Dodge the Creeps" yourself yet, please read - :ref:`doc_your_first_2d_game` before continuing with this tutorial. + `doc_your_first_2d_game` before continuing with this tutorial. Preparing the project --------------------- @@ -208,7 +208,7 @@ Click **Save** and the engine will build the export files. On Windows, if you want your exported executable to have a different icon than the default one, you need to change it manually. See - :ref:`doc_changing_application_icon_for_windows`. + `doc_changing_application_icon_for_windows`. Android ~~~~~~~ diff --git a/tutorials/export/exporting_for_android.rst b/tutorials/export/exporting_for_android.rst index 2fd3b5a..ad1a747 100644 --- a/tutorials/export/exporting_for_android.rst +++ b/tutorials/export/exporting_for_android.rst @@ -8,7 +8,7 @@ Exporting for Android This page describes how to export a Godot project to Android. If you're looking to compile export template binaries from source instead, - read :ref:`doc_compiling_for_android`. + read `doc_compiling_for_android`. Exporting for Android has fewer requirements than compiling Godot for Android. The following steps detail what is needed to set up the Android SDK and the engine. @@ -168,7 +168,7 @@ Each APK should target a single architecture; creating an APK for ARMv7 and ARMv8 is usually sufficient to cover most devices in use today. You can optimize the size further by compiling an Android export template with -only the features you need. See :ref:`doc_optimizing_for_size` for more +only the features you need. See `doc_optimizing_for_size` for more information. Troubleshooting rendering issues @@ -178,4 +178,4 @@ To improve out-of-the-box performance on mobile devices, Godot automatically uses low-end-friendly settings by default on both Android and iOS. This can cause rendering issues that do not occur when running the project on a -desktop platform. See :ref:`doc_mobile_rendering_limitations` for more information. +desktop platform. See `doc_mobile_rendering_limitations` for more information. diff --git a/tutorials/export/exporting_for_dedicated_servers.rst b/tutorials/export/exporting_for_dedicated_servers.rst index c663296..c0cbfae 100644 --- a/tutorials/export/exporting_for_dedicated_servers.rst +++ b/tutorials/export/exporting_for_dedicated_servers.rst @@ -11,8 +11,8 @@ Platform support - **Linux:** `Download an official Linux server binary `__. To compile a server binary from source, follow instructions in - :ref:`doc_compiling_for_x11`. -- **macOS:** :ref:`Compile a server binary from source for macOS `. + `doc_compiling_for_x11`. +- **macOS:** `Compile a server binary from source for macOS `. - **Windows:** There is no dedicated server build for Windows yet. As an alternative, you can use the ``--no-window`` command-line argument to prevent Godot from spawning a window. Note that even with the ``--no-window`` command-line argument, @@ -51,7 +51,7 @@ the bottom of the Export dialog then choose a destination path. The **Export With Debug** checkbox in the file dialog has no bearing on the final PCK file, so you can leave it as-is. -See :ref:`doc_exporting_projects` for more information. +See `doc_exporting_projects` for more information. .. note:: diff --git a/tutorials/export/exporting_for_ios.rst b/tutorials/export/exporting_for_ios.rst index dc01e13..5db7d7b 100644 --- a/tutorials/export/exporting_for_ios.rst +++ b/tutorials/export/exporting_for_ios.rst @@ -7,7 +7,7 @@ Exporting for iOS This page describes how to export a Godot project to iOS. If you're looking to compile export template binaries from source instead, - read :ref:`doc_compiling_for_ios`. + read `doc_compiling_for_ios`. These are the steps to load a Godot project in Xcode. This allows you to build and deploy to an iOS device, build a release for the App Store, and @@ -97,7 +97,7 @@ Plugins for iOS --------------- Special iOS plugins can be used in Godot. Check out the -:ref:`doc_plugins_for_ios` page. +`doc_plugins_for_ios` page. Troubleshooting rendering issues -------------------------------- @@ -106,4 +106,4 @@ To improve out-of-the-box performance on mobile devices, Godot automatically uses low-end-friendly settings by default on both Android and iOS. This can cause rendering issues that do not occur when running the project on a -desktop platform. See :ref:`doc_mobile_rendering_limitations` for more information. +desktop platform. See `doc_mobile_rendering_limitations` for more information. diff --git a/tutorials/export/exporting_for_linux.rst b/tutorials/export/exporting_for_linux.rst index 27d82b3..9e39035 100644 --- a/tutorials/export/exporting_for_linux.rst +++ b/tutorials/export/exporting_for_linux.rst @@ -7,7 +7,7 @@ Exporting for Linux This page describes how to export a Godot project to Linux. If you're looking to compile editor or export template binaries from source instead, - read :ref:`doc_compiling_for_x11`. + read `doc_compiling_for_x11`. The simplest way to distribute a game for PC is to copy the executable (``godot``), compress the folder and send it to someone else. However, this is diff --git a/tutorials/export/exporting_for_macos.rst b/tutorials/export/exporting_for_macos.rst index 4df8b43..b946632 100644 --- a/tutorials/export/exporting_for_macos.rst +++ b/tutorials/export/exporting_for_macos.rst @@ -7,7 +7,7 @@ Exporting for macOS This page describes how to export a Godot project to macOS. If you're looking to compile editor or export template binaries from source instead, - read :ref:`doc_compiling_for_osx`. + read `doc_compiling_for_osx`. macOS apps are exported as an ``.app`` bundle, a folder with a specific structure which stores the executable, libraries and all the project files. This bundle can be exported as is, packed in a ZIP archive or DMG disk image (only supported when exporting from a computer running macOS). @@ -22,12 +22,12 @@ Requirements .. warning:: - Projects exported without code signing and notarization will be blocked by Gatekeeper if they are downloaded from unknown sources, see the :ref:`Running Godot apps on macOS ` page for more information. + Projects exported without code signing and notarization will be blocked by Gatekeeper if they are downloaded from unknown sources, see the `Running Godot apps on macOS ` page for more information. Code signing and notarization ----------------------------- -By default, macOS will run only applications that are signed and notarized. If you use any other signing configuration, see :ref:`Running Godot apps on macOS ` for workarounds. +By default, macOS will run only applications that are signed and notarized. If you use any other signing configuration, see `Running Godot apps on macOS ` for workarounds. To notarize an app, you **must** have a valid `Apple Developer ID Certificate `__. @@ -50,7 +50,7 @@ If you do not have an Apple Developer ID Certificate ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Keep ``Code Signing`` enabled and leave the ``Identity`` option empty (when exporting from a computer running macOS, on other platforms this option is hidden). -In this case Godot will use a ad-hoc signature, which will make running an exported app easier for the end users, see the :ref:`Running Godot apps on macOS ` page for more information. +In this case Godot will use a ad-hoc signature, which will make running an exported app easier for the end users, see the `Running Godot apps on macOS ` page for more information. Signing Options ~~~~~~~~~~~~~~~ diff --git a/tutorials/export/exporting_for_uwp.rst b/tutorials/export/exporting_for_uwp.rst index 729e7ab..0b16292 100644 --- a/tutorials/export/exporting_for_uwp.rst +++ b/tutorials/export/exporting_for_uwp.rst @@ -7,7 +7,7 @@ Exporting for Universal Windows Platform This page describes how to export a Godot project to UWP. If you're looking to compile export template binaries from source instead, - read :ref:`doc_compiling_for_uwp`. + read `doc_compiling_for_uwp`. There's no extra requirement to export an ``.appx`` package that can be installed as a Windows App or submitted to the Windows Store. Exporting UWP diff --git a/tutorials/export/exporting_for_web.rst b/tutorials/export/exporting_for_web.rst index a3b9996..cf12be1 100644 --- a/tutorials/export/exporting_for_web.rst +++ b/tutorials/export/exporting_for_web.rst @@ -7,7 +7,7 @@ Exporting for the Web This page describes how to export a Godot project to HTML5. If you're looking to compile editor or export template binaries from source instead, - read :ref:`doc_compiling_for_web`. + read `doc_compiling_for_web`. HTML5 export allows publishing games made in Godot Engine to the browser. This requires support for `WebAssembly @@ -21,7 +21,7 @@ in the user's browser. .. attention:: `There are significant bugs when running HTML5 projects on iOS `__ (regardless of the browser). We recommend using - :ref:`iOS' native export functionality ` + `iOS' native export functionality ` instead, as it will also result in better performance. WebGL version @@ -62,13 +62,13 @@ You can choose the **Export Type** to select which features will be available: - *GDNative*: enables GDNative support but makes the binary bigger and slower to load. -If you plan to use :ref:`VRAM compression ` make sure that +If you plan to use `VRAM compression ` make sure that **Vram Texture Compression** is enabled for the targeted platforms (enabling both **For Desktop** and **For Mobile** will result in a bigger, but more compatible export). If a path to a **Custom HTML shell** file is given, it will be used instead of -the default HTML page. See :ref:`doc_customizing_html5_shell`. +the default HTML page. See `doc_customizing_html5_shell`. **Head Include** is appended into the ```` element of the generated HTML page. This allows to, for example, load webfonts and third-party @@ -132,18 +132,18 @@ user's side, this can be worked around by running the project in a separate Threads ~~~~~~~ -As mentioned :ref:`above ` multi-threading is +As mentioned `above ` multi-threading is only available if the appropriate **Export Type** is set and support for it across browsers is still limited. -.. warning:: Requires a :ref:`secure context `. +.. warning:: Requires a `secure context `. Browsers also require that the web page is served with specific `cross-origin isolation headers `__. GDNative ~~~~~~~~ -As mentioned :ref:`above ` GDNative is only +As mentioned `above ` GDNative is only available if the appropriate **Export Type** is set. The export will also copy the required GDNative ``.wasm`` files to the output @@ -156,12 +156,12 @@ Browsers do not allow arbitrarily **entering full screen**. The same goes for **capturing the cursor**. Instead, these actions have to occur as a response to a JavaScript input event. In Godot, this means entering full screen from within a pressed input event callback such as ``_input`` or ``_unhandled_input``. -Querying the :ref:`class_Input` singleton is not sufficient, the relevant +Querying the `class_Input` singleton is not sufficient, the relevant input event must currently be active. For the same reason, the full screen project setting doesn't work unless the engine is started from within a valid input event handler. This requires -:ref:`customization of the HTML page `. +`customization of the HTML page `. Audio ~~~~~ @@ -173,16 +173,16 @@ player to click or tap or press a key to enable audio. policies `__. .. warning:: Access to microphone requires a - :ref:`secure context `. + `secure context `. Networking ~~~~~~~~~~ Low level networking is not implemented due to lacking support in browsers. -Currently, only :ref:`HTTP client `, -:ref:`HTTP requests `, -:ref:`WebSocket (client) ` and :ref:`WebRTC ` are +Currently, only `HTTP client `, +`HTTP requests `, +`WebSocket (client) ` and `WebRTC ` are supported. The HTTP classes also have several restrictions on the HTML5 platform: @@ -202,7 +202,7 @@ browser supporting the `Clipboard API `. +.. warning:: Requires a `secure context `. Gamepads ~~~~~~~~ @@ -213,13 +213,13 @@ sadly the `Gamepad API `. +.. warning:: Requires a `secure context `. Boot splash is not displayed ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The default HTML page does not display the boot splash while loading. However, -the image is exported as a PNG file, so :ref:`custom HTML pages ` +the image is exported as a PNG file, so `custom HTML pages ` can display it. Shader language limitations @@ -233,7 +233,7 @@ Serving the files Exporting for the web generates several files to be served from a web server, including a default HTML page for presentation. A custom HTML file can be -used, see :ref:`doc_customizing_html5_shell`. +used, see `doc_customizing_html5_shell`. The generated ``.html`` file can be used as ``DirectoryIndex`` in Apache servers and can be renamed to e.g. ``index.html`` at any time, its name is @@ -249,7 +249,7 @@ the engine. The ``.pck`` file is the Godot main pack containing your game. The ``.js`` file contains start-up code and is used by the ``.html`` file to access the engine. The ``.png`` file contains the boot splash image. It is not used in the default HTML page, but is included for -:ref:`custom HTML pages `. +`custom HTML pages `. The ``.pck`` file is binary, usually delivered with the MIME-type :mimetype:`application/octet-stream`. The ``.wasm`` file is delivered as @@ -288,11 +288,11 @@ languages integrated into Godot. The value of the last JavaScript statement is converted to a GDScript value and returned by ``eval()`` under certain circumstances: - * JavaScript ``number`` is returned as GDScript :ref:`class_float` - * JavaScript ``boolean`` is returned as GDScript :ref:`class_bool` - * JavaScript ``string`` is returned as GDScript :ref:`class_String` + * JavaScript ``number`` is returned as GDScript `class_float` + * JavaScript ``boolean`` is returned as GDScript `class_bool` + * JavaScript ``string`` is returned as GDScript `class_String` * JavaScript ``ArrayBuffer``, ``TypedArray`` and ``DataView`` are returned as - GDScript :ref:`class_PoolByteArray` + GDScript `class_PoolByteArray` :: @@ -302,11 +302,11 @@ returned by ``eval()`` under certain circumstances: Any other JavaScript value is returned as ``null``. -HTML5 export templates may be :ref:`built ` without +HTML5 export templates may be `built ` without support for the singleton to improve security. With such templates, and on platforms other than HTML5, calling ``JavaScript.eval`` will also return ``null``. The availability of the singleton can be checked with the -``JavaScript`` :ref:`feature tag `:: +``JavaScript`` `feature tag `:: func my_func3(): if OS.has_feature('JavaScript'): diff --git a/tutorials/export/exporting_for_windows.rst b/tutorials/export/exporting_for_windows.rst index 0d89ac3..c7aa93f 100644 --- a/tutorials/export/exporting_for_windows.rst +++ b/tutorials/export/exporting_for_windows.rst @@ -7,7 +7,7 @@ Exporting for Windows This page describes how to export a Godot project to Windows. If you're looking to compile editor or export template binaries from source instead, - read :ref:`doc_compiling_for_windows`. + read `doc_compiling_for_windows`. The simplest way to distribute a game for PC is to copy the executable (``godot.exe``), compress the folder and send it to someone else. However, this diff --git a/tutorials/export/exporting_pcks.rst b/tutorials/export/exporting_pcks.rst index a4f7412..f3fee0f 100644 --- a/tutorials/export/exporting_pcks.rst +++ b/tutorials/export/exporting_pcks.rst @@ -60,7 +60,7 @@ an export template selected while doing so. .. image:: img/export_pck.png -Another method would be to :ref:`export from the command line `. +Another method would be to `export from the command line `. If the output file ends with a PCK or ZIP file extension, then the export process will build that type of file for the chosen platform. @@ -82,7 +82,7 @@ process will build that type of file for the chosen platform. build of the engine or have access to one (distributed alongside or perhaps in the original game's files). The tool can then use the Godot executable to export a PCK file from the command line with - :ref:`OS.execute() `. The game itself shouldn't + `OS.execute() `. The game itself shouldn't use a tool-build of the engine (for security), so it's best to keep the modding tool and game separate. @@ -114,7 +114,7 @@ gdscript GDScript PCK file of this kind can fix the content of a previously loaded PCK. To opt out of this behavior, pass ``false`` as the second argument to - :ref:`ProjectSettings.load_resource_pack() `. + `ProjectSettings.load_resource_pack() `. .. note:: For a C# project, you need to build the DLL and place it in the project directory first. diff --git a/tutorials/export/exporting_projects.rst b/tutorials/export/exporting_projects.rst index fc5fe94..16719cd 100644 --- a/tutorials/export/exporting_projects.rst +++ b/tutorials/export/exporting_projects.rst @@ -32,7 +32,7 @@ binary, which is smaller in size, more optimized and does not include tools like the editor and debugger. Finally, Godot has a simple but efficient system for -:ref:`creating DLCs as extra package files `. +`creating DLCs as extra package files `. On mobile ~~~~~~~~~ @@ -179,7 +179,7 @@ the command: .. seealso:: - See :ref:`doc_command_line_tutorial` for more information about using Godot + See `doc_command_line_tutorial` for more information about using Godot from the command line. PCK versus ZIP pack file formats @@ -201,7 +201,7 @@ depending on your needs. - Compressed format. Smaller file size, but slower to read/write. - Readable and writable using tools normally present on the user's operating system. - This can be useful to make modding easier (see also :ref:`doc_exporting_pcks`). + This can be useful to make modding easier (see also `doc_exporting_pcks`). .. warning:: diff --git a/tutorials/export/feature_tags.rst b/tutorials/export/feature_tags.rst index 7c7988b..448ec4d 100644 --- a/tutorials/export/feature_tags.rst +++ b/tutorials/export/feature_tags.rst @@ -36,7 +36,7 @@ Here is a list of most feature tags in Godot. Keep in mind they are **case-sensi +-----------------+--------------------------------------------------------+ | **HTML5** | Running on HTML5 | +-----------------+--------------------------------------------------------+ -| **JavaScript** | :ref:`JavaScript singleton ` is | +| **JavaScript** | `JavaScript singleton ` is | | | available | +-----------------+--------------------------------------------------------+ | **OSX** | Running on macOS | @@ -94,7 +94,7 @@ Here is a list of most feature tags in Godot. Keep in mind they are **case-sensi ``false`` when running a project exported to HTML5 on a mobile device. To check whether a project exported to HTML5 is running on a mobile device, - :ref:`call JavaScript code ` that reads the browser's + `call JavaScript code ` that reads the browser's user agent. Custom features @@ -108,7 +108,7 @@ field in the *export preset* used to generate it: .. note:: Custom feature tags are only used when running the exported project - (including with :ref:`doc_one-click_deploy`). They are **not used** when + (including with `doc_one-click_deploy`). They are **not used** when running the project from the editor, even if the export preset marked as **Runnable** for your current platform has custom feature tags defined. @@ -130,7 +130,7 @@ After overriding, a new field is added for this specific configuration: .. note:: When using the - :ref:`project settings "override.cfg" functionality ` + `project settings "override.cfg" functionality ` (which is unrelated to feature tags), remember that feature tags still apply. Therefore, make sure to *also* override the setting with the desired feature tag(s) if you want them to override base project settings on all platforms diff --git a/tutorials/export/one-click_deploy.rst b/tutorials/export/one-click_deploy.rst index 07e64df..5c37dc7 100644 --- a/tutorials/export/one-click_deploy.rst +++ b/tutorials/export/one-click_deploy.rst @@ -31,7 +31,7 @@ Supported platforms - **Android:** Exports the project with debugging enabled and runs it on the connected device. - - Make sure to follow the steps described in :ref:`doc_exporting_for_android`. + - Make sure to follow the steps described in `doc_exporting_for_android`. Otherwise, the one-click deploy button won't appear. - If you have more than one device connected, Godot will ask you which device diff --git a/tutorials/export/running_on_macos.rst b/tutorials/export/running_on_macos.rst index c430891..bcc3d14 100644 --- a/tutorials/export/running_on_macos.rst +++ b/tutorials/export/running_on_macos.rst @@ -6,7 +6,7 @@ Running Godot apps on macOS .. seealso:: This page covers running Godot projects on macOS. - If you haven't exported your project yet, read :ref:`doc_exporting_for_macos` first. + If you haven't exported your project yet, read `doc_exporting_for_macos` first. By default, macOS will run only applications that are signed and notarized. diff --git a/tutorials/i18n/internationalizing_games.rst b/tutorials/i18n/internationalizing_games.rst index e1ff8d3..467aa91 100644 --- a/tutorials/i18n/internationalizing_games.rst +++ b/tutorials/i18n/internationalizing_games.rst @@ -18,7 +18,7 @@ Localization is usually done by specific studios hired for the job and, despite the huge amount of software and file formats available for this, the most common way to do localization to this day is still with spreadsheets. The process of creating the spreadsheets and importing -them is already covered in the :ref:`doc_importing_translations` tutorial, +them is already covered in the `doc_importing_translations` tutorial, so this one could be seen more like a follow-up to that one. @@ -51,7 +51,7 @@ locale. Converting keys to text ----------------------- -Some controls, such as :ref:`Button ` and :ref:`Label `, +Some controls, such as `Button ` and `Label `, will automatically fetch a translation if their text matches a translation key. For example, if a label's text is "MAIN_SCREEN_GREETING1" and that key exists in the current translation, then the text will automatically be translated. @@ -60,8 +60,8 @@ This automatic translation behavior may be undesirable in certain cases. For instance, when using a Label to display a player's name, you most likely don't want the player's name to be translated if it matches a translation key. To disable automatic translation on a specific node, use -:ref:`Object.set_message_translation` -and send a :ref:`Object.notification` to update the +`Object.set_message_translation` +and send a `Object.notification` to update the translation:: func _ready(): @@ -80,7 +80,7 @@ For more complex UI nodes such as OptionButtons, you may have to use this instea option_button.get_popup().set_message_translation(false) option_button.get_popup().notification(NOTIFICATION_TRANSLATION_CHANGED) -In code, the :ref:`Object.tr() ` +In code, the `Object.tr() ` function can be used. This will just look up the text in the translations and convert it if found: @@ -93,16 +93,16 @@ Making controls resizable -------------------------- The same text in different languages can vary greatly in length. For -this, make sure to read the tutorial on :ref:`doc_size_and_anchors`, as +this, make sure to read the tutorial on `doc_size_and_anchors`, as dynamically adjusting control sizes may help. -:ref:`Container ` can be useful, as well as the text wrapping -options available in :ref:`Label `. +`Container ` can be useful, as well as the text wrapping +options available in `Label `. TranslationServer ----------------- Godot has a server handling low-level translation management -called the :ref:`TranslationServer `. +called the `TranslationServer `. Translations can be added or removed during run-time; the current language can also be changed at run-time. @@ -143,4 +143,4 @@ For instance, for Spanish, this would be ``application/name_es``: .. image:: img/localized_name.png If you are unsure about the language code to use, refer to the -:ref:`list of locale codes `. +`list of locale codes `. diff --git a/tutorials/i18n/localization_using_gettext.rst b/tutorials/i18n/localization_using_gettext.rst index ae13162..5b778dc 100644 --- a/tutorials/i18n/localization_using_gettext.rst +++ b/tutorials/i18n/localization_using_gettext.rst @@ -3,7 +3,7 @@ Localization using gettext ========================== -In addition to :ref:`doc_importing_translations` in CSV format, Godot +In addition to `doc_importing_translations` in CSV format, Godot also supports loading translation files written in the GNU gettext format (text-based ``.po`` and compiled ``.mo`` since Godot 3.5). @@ -117,7 +117,7 @@ You can then run pybabel like so: pybabel extract -F babelrc -k text -k LineEdit/placeholder_text -k tr -o godot-l10n.pot . Use the ``-k`` option to specify what needs to be extracted. In this case, -arguments to :ref:`tr() ` will be translated, as well +arguments to `tr() ` will be translated, as well as properties named "text" (commonly used by Control nodes) and LineEdit's "placeholder_text" property. @@ -147,7 +147,7 @@ In **Translations**, click **Add…** then choose the ``.po`` or ``.mo`` file in the file dialog. The locale will be inferred from the ``"Language: \n"`` property in the messages file. -.. note:: See :ref:`doc_internationalizing_games` for more information on +.. note:: See `doc_internationalizing_games` for more information on importing and testing translations in Godot. Updating message files to follow the PO template diff --git a/tutorials/inputs/controllers_gamepads_joysticks.rst b/tutorials/inputs/controllers_gamepads_joysticks.rst index a42987b..0def147 100644 --- a/tutorials/inputs/controllers_gamepads_joysticks.rst +++ b/tutorials/inputs/controllers_gamepads_joysticks.rst @@ -30,7 +30,7 @@ Instead of hardcoding keys or controller buttons in your scripts, you should create *input actions* in the Project Settings which will then refer to specified key and controller inputs. -Input actions are explained in detail on the :ref:`doc_inputevent` page. +Input actions are explained in detail on the `doc_inputevent` page. .. note:: @@ -143,10 +143,10 @@ known as "echo" events). This is because the operating system never sends "echo" events for controller input in the first place. If you want controller buttons to send echo events, you will have to generate -:ref:`class_InputEvent` objects by code and parse them using -:ref:`Input.parse_input_event() ` +`class_InputEvent` objects by code and parse them using +`Input.parse_input_event() ` at regular intervals. This can be accomplished -with the help of a :ref:`class_Timer` node. +with the help of a `class_Timer` node. Troubleshooting --------------- @@ -200,7 +200,7 @@ powershell Windows (powershell) To test mappings on non-desktop platforms or to distribute your project with additional controller mappings, you can add them by calling -:ref:`Input.add_joy_mapping() ` +`Input.add_joy_mapping() ` as early as possible in a script's ``_ready()`` function. My controller works on a given platform, but not on another platform. diff --git a/tutorials/inputs/custom_mouse_cursor.rst b/tutorials/inputs/custom_mouse_cursor.rst index 5958780..248223a 100644 --- a/tutorials/inputs/custom_mouse_cursor.rst +++ b/tutorials/inputs/custom_mouse_cursor.rst @@ -59,7 +59,7 @@ gdscript GDScript ``` .. note:: - Check :ref:`Input.set_custom_mouse_cursor() `. + Check `Input.set_custom_mouse_cursor() `. Demo project @@ -71,4 +71,4 @@ https://github.com/guilhermefelipecgs/custom_hardware_cursor Cursor list ----------- -As documented in the :ref:`Input ` class (see the **CursorShape** enum), there are multiple mouse cursors you can define. Which ones you want to use depends on your use case. +As documented in the `Input ` class (see the **CursorShape** enum), there are multiple mouse cursors you can define. Which ones you want to use depends on your use case. diff --git a/tutorials/inputs/handling_quit_requests.rst b/tutorials/inputs/handling_quit_requests.rst index 8bb092d..00902f0 100644 --- a/tutorials/inputs/handling_quit_requests.rst +++ b/tutorials/inputs/handling_quit_requests.rst @@ -14,7 +14,7 @@ to go back otherwise). Handling the notification ------------------------- -On desktop platforms, the :ref:`MainLoop ` +On desktop platforms, the `MainLoop ` has a special ``MainLoop.NOTIFICATION_WM_QUIT_REQUEST`` notification that is sent to all nodes when quitting is requested. @@ -53,10 +53,10 @@ gdscript GDScript Sending your own quit notification ---------------------------------- -While forcing the application to close can be done by calling :ref:`SceneTree.quit `, +While forcing the application to close can be done by calling `SceneTree.quit `, doing so will not send the quit *notification*. This means the function described above won't be called. Quitting by calling -:ref:`SceneTree.quit ` will not allow custom actions +`SceneTree.quit ` will not allow custom actions to complete (such as saving, confirming the quit, or debugging), even if you try to delay the line that forces the quit. diff --git a/tutorials/inputs/input_examples.rst b/tutorials/inputs/input_examples.rst index d34ab28..7a77733 100644 --- a/tutorials/inputs/input_examples.rst +++ b/tutorials/inputs/input_examples.rst @@ -6,7 +6,7 @@ Input examples Introduction ------------ -In this tutorial, you'll learn how to use Godot's :ref:`InputEvent ` +In this tutorial, you'll learn how to use Godot's `InputEvent ` system to capture player input. There are many different types of input your game may use - keyboard, gamepad, mouse, etc. - and many different ways to turn those inputs into actions in your game. This document will show you some @@ -14,7 +14,7 @@ of the most common scenarios, which you can use as starting points for your own projects. .. note:: For a detailed overview of how Godot's input event system works, - see :ref:`doc_inputevent`. + see `doc_inputevent`. Events versus polling --------------------- @@ -23,7 +23,7 @@ Sometimes you want your game to respond to a certain input event - pressing the "jump" button, for example. For other situations, you might want something to happen as long as a key is pressed, such as movement. In the first case, you can use the ``_input()`` function, which will be called whenever an input -event occurs. In the second case, Godot provides the :ref:`Input ` +event occurs. In the second case, Godot provides the `Input ` singleton, which you can use to query the state of an input. Examples: @@ -51,7 +51,7 @@ events in ``_input()``. Input events ------------ -Input events are objects that inherit from :ref:`InputEvent `. +Input events are objects that inherit from `InputEvent `. Depending on the event type, the object will contain specific properties related to that event. To see what events actually look like, add a Node and attach the following script: @@ -82,13 +82,13 @@ event scroll by in the output window. Here's an example of the output: As you can see, the results are very different for the different types of input. Key events are even printed as their key symbols. For example, let's -consider :ref:`InputEventMouseButton `. +consider `InputEventMouseButton `. It inherits from the following classes: -- :ref:`InputEvent ` - the base class for all input events -- :ref:`InputEventWithModifiers ` - adds the ability to check if modifiers are pressed, such as :kbd:`Shift` or :kbd:`Alt`. -- :ref:`InputEventMouse ` - adds mouse event properties, such as ``position`` -- :ref:`InputEventMouseButton ` - contains the index of the button that was pressed, whether it was a double-click, etc. +- `InputEvent ` - the base class for all input events +- `InputEventWithModifiers ` - adds the ability to check if modifiers are pressed, such as :kbd:`Shift` or :kbd:`Alt`. +- `InputEventMouse ` - adds mouse event properties, such as ``position`` +- `InputEventMouseButton ` - contains the index of the button that was pressed, whether it was a double-click, etc. .. tip:: It's a good idea to keep the class reference open while you're working with events so you can check the event type's available properties and @@ -109,7 +109,7 @@ gdscript GDScript InputMap -------- -The :ref:`InputMap ` is the most flexible way to handle a +The `InputMap ` is the most flexible way to handle a variety of inputs. You use this by creating named input *actions*, to which you can assign any number of input events, such as keypresses or mouse clicks. A new Godot project includes a number of default actions already defined. To @@ -136,7 +136,7 @@ gdscript GDScript Keyboard events --------------- -Keyboard events are captured in :ref:`InputEventKey `. +Keyboard events are captured in `InputEventKey `. While it's recommended to use input actions instead, there may be cases where you want to specifically look at key events. For this example, let's check for the :kbd:`T`: @@ -150,7 +150,7 @@ gdscript GDScript print("T was pressed") ``` -.. tip:: See :ref:`@GlobalScope_KeyList ` for a list of scancode +.. tip:: See `@GlobalScope_KeyList ` for a list of scancode constants. .. warning:: @@ -170,7 +170,7 @@ Keyboard modifiers ~~~~~~~~~~~~~~~~~~ Modifier properties are inherited from -:ref:`InputEventWithModifiers `. This allows +`InputEventWithModifiers `. This allows you to check for modifier combinations using boolean properties. Let's imagine you want one thing to happen when the :kbd:`T` is pressed, but something different when it's :kbd:`Shift + T`: @@ -187,21 +187,21 @@ gdscript GDScript print("T was pressed") ``` -.. tip:: See :ref:`@GlobalScope_KeyList ` for a list of scancode +.. tip:: See `@GlobalScope_KeyList ` for a list of scancode constants. Mouse events ------------ -Mouse events stem from the :ref:`InputEventMouse ` class, and -are separated into two types: :ref:`InputEventMouseButton ` -and :ref:`InputEventMouseMotion `. Note that this +Mouse events stem from the `InputEventMouse ` class, and +are separated into two types: `InputEventMouseButton ` +and `InputEventMouseMotion `. Note that this means that all mouse events will contain a ``position`` property. Mouse buttons ~~~~~~~~~~~~~ -Capturing mouse buttons is very similar to handling key events. :ref:`@GlobalScope_ButtonList ` +Capturing mouse buttons is very similar to handling key events. `@GlobalScope_ButtonList ` contains a list of ``BUTTON_*`` constants for each possible button, which will be reported in the event's ``button_index`` property. Note that the scrollwheel also counts as a button - two buttons, to be precise, with both @@ -221,11 +221,11 @@ gdscript GDScript Mouse motion ~~~~~~~~~~~~ -:ref:`InputEventMouseMotion ` events occur whenever +`InputEventMouseMotion ` events occur whenever the mouse moves. You can find the move's distance with the ``relative`` property. -Here's an example using mouse events to drag-and-drop a :ref:`Sprite ` +Here's an example using mouse events to drag-and-drop a `Sprite ` node: gdscript GDScript @@ -257,8 +257,8 @@ Touch events ------------ If you are using a touchscreen device, you can generate touch events. -:ref:`InputEventScreenTouch ` is equivalent to -a mouse click event, and :ref:`InputEventScreenDrag ` +`InputEventScreenTouch ` is equivalent to +a mouse click event, and `InputEventScreenDrag ` works much the same as mouse motion. .. tip:: To test your touch events on a non-touchscreen device, open Project diff --git a/tutorials/inputs/inputevent.rst b/tutorials/inputs/inputevent.rst index be0a1c8..39a2971 100644 --- a/tutorials/inputs/inputevent.rst +++ b/tutorials/inputs/inputevent.rst @@ -7,7 +7,7 @@ What is it? ----------- Managing input is usually complex, no matter the OS or platform. To ease -this a little, a special built-in type is provided, :ref:`InputEvent `. +this a little, a special built-in type is provided, `InputEvent `. This datatype can be configured to contain several types of input events. Input events travel through the engine and can be received in multiple locations, depending on the purpose. @@ -23,7 +23,7 @@ gdscript GDScript get_tree().quit() ``` -However, it is cleaner and more flexible to use the provided :ref:`InputMap ` feature, +However, it is cleaner and more flexible to use the provided `InputMap ` feature, which allows you to define input actions and assign them different keys. This way, you can define multiple keys for the same action (e.g. the keyboard escape key and the start button on a gamepad). You can then more easily change this mapping in the project settings without updating your code, @@ -45,44 +45,44 @@ How does it work? Every input event is originated from the user/player (though it's possible to generate an InputEvent and feed them back to the engine, which is useful for gestures). The OS object for each platform will read -events from the device, then feed them to MainLoop. As :ref:`SceneTree ` +events from the device, then feed them to MainLoop. As `SceneTree ` is the default MainLoop implementation, events are fed to it. Godot provides a function to get the current SceneTree object : **get_tree()**. But SceneTree does not know what to do with the event, so it will give -it to the viewports, starting by the "root" :ref:`Viewport ` (the first +it to the viewports, starting by the "root" `Viewport ` (the first node of the scene tree). Viewport does quite a lot of stuff with the received input, in order: .. image:: img/input_event_flow.png -1. First of all, the standard :ref:`Node._input() ` function - will be called in any node that overrides it (and hasn't disabled input processing with :ref:`Node.set_process_input() `). - If any function consumes the event, it can call :ref:`SceneTree.set_input_as_handled() `, and the event will +1. First of all, the standard `Node._input() ` function + will be called in any node that overrides it (and hasn't disabled input processing with `Node.set_process_input() `). + If any function consumes the event, it can call `SceneTree.set_input_as_handled() `, and the event will not spread any more. This ensures that you can filter all events of interest, even before the GUI. - For gameplay input, :ref:`Node._unhandled_input() ` is generally a better fit, because it allows the GUI to intercept the events. + For gameplay input, `Node._unhandled_input() ` is generally a better fit, because it allows the GUI to intercept the events. 2. Second, it will try to feed the input to the GUI, and see if any - control can receive it. If so, the :ref:`Control ` will be called via the - virtual function :ref:`Control._gui_input() ` and the signal + control can receive it. If so, the `Control ` will be called via the + virtual function `Control._gui_input() ` and the signal "gui_input" will be emitted (this function is re-implementable by script by inheriting from it). If the control wants to "consume" the - event, it will call :ref:`Control.accept_event() ` and the event will - not spread any more. Use the :ref:`Control.mouse_filter ` - property to control whether a :ref:`Control ` is notified - of mouse events via :ref:`Control._gui_input() ` + event, it will call `Control.accept_event() ` and the event will + not spread any more. Use the `Control.mouse_filter ` + property to control whether a `Control ` is notified + of mouse events via `Control._gui_input() ` callback, and whether these events are propagated further. 3. If so far no one consumed the event, the unhandled input callback will be called if overridden (and not disabled with - :ref:`Node.set_process_unhandled_input() `). - If any function consumes the event, it can call :ref:`SceneTree.set_input_as_handled() `, and the + `Node.set_process_unhandled_input() `). + If any function consumes the event, it can call `SceneTree.set_input_as_handled() `, and the event will not spread any more. The unhandled input callback is ideal for full-screen gameplay events, so they are not received when a GUI is active. -4. If no one wanted the event so far, and a :ref:`Camera ` is assigned - to the Viewport with :ref:`Object Picking ` turned on, a ray to the physics world (in the ray direction from - the click) will be cast. (For the root viewport, this can also be enabled in :ref:`Project Settings `) If this ray hits an object, it will call the - :ref:`CollisionObject._input_event() ` function in the relevant +4. If no one wanted the event so far, and a `Camera ` is assigned + to the Viewport with `Object Picking ` turned on, a ray to the physics world (in the ray direction from + the click) will be cast. (For the root viewport, this can also be enabled in `Project Settings `) If this ray hits an object, it will call the + `CollisionObject._input_event() ` function in the relevant physics object (bodies receive this callback by default, but areas do - not. This can be configured through :ref:`Area ` properties). + not. This can be configured through `Area ` properties). 5. Finally, if the event was unhandled, it will be passed to the next Viewport in the tree, otherwise it will be ignored. @@ -103,7 +103,7 @@ generalized behavior if needed. Anatomy of an InputEvent ------------------------ -:ref:`InputEvent ` is just a base built-in type, it does not represent +`InputEvent ` is just a base built-in type, it does not represent anything and only contains some basic information, such as event ID (which is increased for each event), device index, etc. @@ -112,31 +112,31 @@ There are several specialized types of InputEvent, described in the table below: +-------------------------------------------------------------------+--------------------+-----------------------------------------+ | Event | Type Index | Description | +-------------------------------------------------------------------+--------------------+-----------------------------------------+ -| :ref:`InputEvent ` | NONE | Empty Input Event. | +| `InputEvent ` | NONE | Empty Input Event. | +-------------------------------------------------------------------+--------------------+-----------------------------------------+ -| :ref:`InputEventKey ` | KEY | Contains a scancode and Unicode value, | +| `InputEventKey ` | KEY | Contains a scancode and Unicode value, | | | | as well as modifiers. | +-------------------------------------------------------------------+--------------------+-----------------------------------------+ -| :ref:`InputEventMouseButton ` | MOUSE_BUTTON | Contains click information, such as | +| `InputEventMouseButton ` | MOUSE_BUTTON | Contains click information, such as | | | | button, modifiers, etc. | +-------------------------------------------------------------------+--------------------+-----------------------------------------+ -| :ref:`InputEventMouseMotion ` | MOUSE_MOTION | Contains motion information, such as | +| `InputEventMouseMotion ` | MOUSE_MOTION | Contains motion information, such as | | | | relative, absolute positions and speed. | +-------------------------------------------------------------------+--------------------+-----------------------------------------+ -| :ref:`InputEventJoypadMotion ` | JOYSTICK_MOTION | Contains Joystick/Joypad analog axis | +| `InputEventJoypadMotion ` | JOYSTICK_MOTION | Contains Joystick/Joypad analog axis | | | | information. | +-------------------------------------------------------------------+--------------------+-----------------------------------------+ -| :ref:`InputEventJoypadButton ` | JOYSTICK_BUTTON | Contains Joystick/Joypad button | +| `InputEventJoypadButton ` | JOYSTICK_BUTTON | Contains Joystick/Joypad button | | | | information. | +-------------------------------------------------------------------+--------------------+-----------------------------------------+ -| :ref:`InputEventScreenTouch ` | SCREEN_TOUCH | Contains multi-touch press/release | +| `InputEventScreenTouch ` | SCREEN_TOUCH | Contains multi-touch press/release | | | | information. (only available on mobile | | | | devices) | +-------------------------------------------------------------------+--------------------+-----------------------------------------+ -| :ref:`InputEventScreenDrag ` | SCREEN_DRAG | Contains multi-touch drag information. | +| `InputEventScreenDrag ` | SCREEN_DRAG | Contains multi-touch drag information. | | | | (only available on mobile devices) | +-------------------------------------------------------------------+--------------------+-----------------------------------------+ -| :ref:`InputEventAction ` | SCREEN_ACTION | Contains a generic action. These events | +| `InputEventAction ` | SCREEN_ACTION | Contains a generic action. These events | | | | are often generated by the programmer | | | | as feedback. (more on this below) | +-------------------------------------------------------------------+--------------------+-----------------------------------------+ @@ -155,13 +155,13 @@ logic. This allows for: Actions can be created from the Project Settings menu in the Actions tab. -Any event has the methods :ref:`InputEvent.is_action() `, -:ref:`InputEvent.is_pressed() ` and :ref:`InputEvent `. +Any event has the methods `InputEvent.is_action() `, +`InputEvent.is_pressed() ` and `InputEvent `. Alternatively, it may be desired to supply the game back with an action from the game code (a good example of this is detecting gestures). The Input singleton has a method for this: -:ref:`Input.parse_input_event() `. You would normally use it like this: +`Input.parse_input_event() `. You would normally use it like this: gdscript GDScript @@ -178,7 +178,7 @@ InputMap -------- Customizing and re-mapping input from code is often desired. If your -whole workflow depends on actions, the :ref:`InputMap ` singleton is +whole workflow depends on actions, the `InputMap ` singleton is ideal for reassigning or creating different actions at run-time. This singleton is not saved (must be modified manually) and its state is run from the project settings (project.godot). So any dynamic system of this diff --git a/tutorials/inputs/mouse_and_input_coordinates.rst b/tutorials/inputs/mouse_and_input_coordinates.rst index 4a83478..29eb619 100644 --- a/tutorials/inputs/mouse_and_input_coordinates.rst +++ b/tutorials/inputs/mouse_and_input_coordinates.rst @@ -21,7 +21,7 @@ Viewport display coordinates ---------------------------- Godot uses viewports to display content, and viewports can be scaled by -several options (see :ref:`doc_multiple_resolutions` tutorial). Use, then, the +several options (see `doc_multiple_resolutions` tutorial). Use, then, the functions in nodes to obtain the mouse coordinates and viewport size, for example: diff --git a/tutorials/io/background_loading.rst b/tutorials/io/background_loading.rst index bd2cc77..694f6c9 100644 --- a/tutorials/io/background_loading.rst +++ b/tutorials/io/background_loading.rst @@ -87,7 +87,7 @@ Example ------- This example demonstrates how to load a new scene. Consider it in the -context of the :ref:`doc_singletons_autoload` example. +context of the `doc_singletons_autoload` example. First, we set up some variables and initialize the ``current_scene`` with the main scene of the game: diff --git a/tutorials/io/binary_serialization_api.rst b/tutorials/io/binary_serialization_api.rst index 763b4ab..3ebf077 100644 --- a/tutorials/io/binary_serialization_api.rst +++ b/tutorials/io/binary_serialization_api.rst @@ -8,8 +8,8 @@ Introduction Godot has a simple serialization API based on Variant. It's used for converting data types to an array of bytes efficiently. This API is used -in the functions ``get_var`` and ``store_var`` of :ref:`class_File` -as well as the packet APIs for :ref:`class_PacketPeer`. This format +in the functions ``get_var`` and ``store_var`` of `class_File` +as well as the packet APIs for `class_PacketPeer`. This format is *not* used for binary scenes and resources. Packet specification @@ -95,7 +95,7 @@ precision. 0: null ~~~~~~~ -1: :ref:`bool` +1: `bool` ~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------+-------+-----------+---------------------------+ @@ -104,7 +104,7 @@ precision. | 4 | 4 | Integer | 0 for False, 1 for True | +----------+-------+-----------+---------------------------+ -2: :ref:`int` +2: `int` ~~~~~~~~~~~~~~~~~~~~~~~~ If no flags are set (flags == 0), the integer is sent as a 32 bit integer: @@ -124,7 +124,7 @@ a 64-bit integer: | 4 | 8 | Integer | 64-bit signed integer | +----------+-------+-----------+--------------------------+ -3: :ref:`float` +3: `float` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If no flags are set (flags == 0), the float is sent as a 32 bit single precision: @@ -144,7 +144,7 @@ a 64-bit double precision number: | 4 | 8 | Float | IEEE 754 double-precision float | +----------+-------+---------+-----------------------------------+ -4: :ref:`String` +4: `String` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------+-------+-----------+----------------------------+ @@ -157,7 +157,7 @@ a 64-bit double precision number: This field is padded to 4 bytes. -5: :ref:`Vector2` +5: `Vector2` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------+-------+---------+----------------+ @@ -168,7 +168,7 @@ This field is padded to 4 bytes. | 8 | 4 | Float | Y coordinate | +----------+-------+---------+----------------+ -6: :ref:`Rect2` +6: `Rect2` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------+-------+---------+----------------+ @@ -183,7 +183,7 @@ This field is padded to 4 bytes. | 16 | 4 | Float | Y size | +----------+-------+---------+----------------+ -7: :ref:`Vector3` +7: `Vector3` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------+-------+---------+----------------+ @@ -196,7 +196,7 @@ This field is padded to 4 bytes. | 12 | 4 | Float | Z coordinate | +----------+-------+---------+----------------+ -8: :ref:`Transform2D` +8: `Transform2D` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------+-------+---------+---------------------------------------------------------------+ @@ -215,7 +215,7 @@ This field is padded to 4 bytes. | 24 | 4 | Float | The Y component of the origin vector, accessed via [2][1] | +----------+-------+---------+---------------------------------------------------------------+ -9: :ref:`Plane` +9: `Plane` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------+-------+---------+---------------+ @@ -230,7 +230,7 @@ This field is padded to 4 bytes. | 16 | 4 | Float | Distance | +----------+-------+---------+---------------+ -10: :ref:`Quat` +10: `Quat` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------+-------+---------+---------------+ @@ -245,7 +245,7 @@ This field is padded to 4 bytes. | 16 | 4 | Float | Real W | +----------+-------+---------+---------------+ -11: :ref:`AABB` +11: `AABB` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------+-------+---------+----------------+ @@ -264,7 +264,7 @@ This field is padded to 4 bytes. | 24 | 4 | Float | Z size | +----------+-------+---------+----------------+ -12: :ref:`Basis` +12: `Basis` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------+-------+---------+---------------------------------------------------------------+ @@ -289,7 +289,7 @@ This field is padded to 4 bytes. | 36 | 4 | Float | The Z component of the Z column vector, accessed via [2][2] | +----------+-------+---------+---------------------------------------------------------------+ -13: :ref:`Transform` +13: `Transform` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------+-------+---------+---------------------------------------------------------------+ @@ -320,7 +320,7 @@ This field is padded to 4 bytes. | 48 | 4 | Float | The Z component of the origin vector, accessed via [3][2] | +----------+-------+---------+---------------------------------------------------------------+ -14: :ref:`Color` +14: `Color` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------+-------+---------+--------------------------------------------------------------+ @@ -335,7 +335,7 @@ This field is padded to 4 bytes. | 16 | 4 | Float | Alpha (0..1) | +----------+-------+---------+--------------------------------------------------------------+ -15: :ref:`NodePath` +15: `NodePath` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------+-------+-----------+-----------------------------------------------------------------------------------------+ @@ -378,13 +378,13 @@ For each Name and Sub-Name Every name string is padded to 4 bytes. -16: :ref:`RID` (unsupported) +16: `RID` (unsupported) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -17: :ref:`Object` (unsupported) +17: `Object` (unsupported) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -18: :ref:`Dictionary` +18: `Dictionary` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------+-------+-----------+---------------------------------------------------------------------+ @@ -396,7 +396,7 @@ Every name string is padded to 4 bytes. Then what follows is, for amount of "elements", pairs of key and value, one after the other, using this same format. -19: :ref:`Array` +19: `Array` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------+-------+-----------+---------------------------------------------------------------------+ @@ -408,7 +408,7 @@ one after the other, using this same format. Then what follows is, for amount of "elements", values one after the other, using this same format. -20: :ref:`PoolByteArray` +20: `PoolByteArray` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------+-------+-----------+------------------------+ @@ -421,7 +421,7 @@ other, using this same format. The array data is padded to 4 bytes. -21: :ref:`PoolIntArray` +21: `PoolIntArray` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------+-------+-----------+---------------------------+ @@ -432,7 +432,7 @@ The array data is padded to 4 bytes. | 8..8+length\*4 | 4 | Integer | 32-bit signed integer | +------------------+-------+-----------+---------------------------+ -22: :ref:`PoolRealArray` +22: `PoolRealArray` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------+-------+-----------+---------------------------+ @@ -443,7 +443,7 @@ The array data is padded to 4 bytes. | 8..8+length\*4 | 4 | Integer | 32-bits IEEE 754 float | +------------------+-------+-----------+---------------------------+ -23: :ref:`PoolStringArray` +23: `PoolStringArray` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------+-------+-----------+--------------------------+ @@ -464,7 +464,7 @@ For each String: Every string is padded to 4 bytes. -24: :ref:`PoolVector2Array` +24: `PoolVector2Array` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +-------------------+-------+-----------+----------------+ @@ -477,7 +477,7 @@ Every string is padded to 4 bytes. | 8..12+length\*8 | 4 | Float | Y coordinate | +-------------------+-------+-----------+----------------+ -25: :ref:`PoolVector3Array` +25: `PoolVector3Array` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------+-------+-----------+----------------+ @@ -492,7 +492,7 @@ Every string is padded to 4 bytes. | 8..16+length\*12 | 4 | Float | Z coordinate | +--------------------+-------+-----------+----------------+ -26: :ref:`PoolColorArray` +26: `PoolColorArray` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------+-------+-----------+--------------------------------------------------------------+ diff --git a/tutorials/io/data_paths.rst b/tutorials/io/data_paths.rst index 4b4d135..29481cf 100644 --- a/tutorials/io/data_paths.rst +++ b/tutorials/io/data_paths.rst @@ -52,17 +52,17 @@ The location of the ``user://`` folder depends on what is configured in the Project Settings: - By default, the ``user://`` folder is created within Godot's - :ref:`editor data path ` in the + `editor data path ` in the ``app_userdata/[project_name]`` folder. This is the default so that prototypes and test projects stay self-contained within Godot's data folder. -- If :ref:`application/config/use_custom_user_dir ` +- If `application/config/use_custom_user_dir ` is enabled in the Project Settings, the ``user://`` folder is created **next to** Godot's editor data path, i.e. in the standard location for applications data. * By default, the folder name will be inferred from the project name, but it can be further customized with - :ref:`application/config/custom_user_dir_name `. + `application/config/custom_user_dir_name `. This path can contain path separators, so you can use it e.g. to group projects of a given studio with a ``Studio Name/Game Name`` structure. @@ -85,27 +85,27 @@ On desktop platforms, the actual directory paths for ``user://`` are: +---------------------+------------------------------------------------------------------------------+ ``[project_name]`` is based on the application name defined in the Project Settings, but -you can override it on a per-platform basis using :ref:`feature tags `. +you can override it on a per-platform basis using `feature tags `. On mobile platforms, this path is unique to the project and is not accessible by other applications for security reasons. On HTML5 exports, ``user://`` will refer to a virtual filesystem stored on the device via IndexedDB. (Interaction with the main filesystem can still be performed -through the :ref:`JavaScript ` singleton.) +through the `JavaScript ` singleton.) Converting paths to absolute paths or "local" paths --------------------------------------------------- -You can use :ref:`ProjectSettings.globalize_path() ` +You can use `ProjectSettings.globalize_path() ` to convert a "local" path like ``res://path/to/file.txt`` to an absolute OS path. -For example, :ref:`ProjectSettings.globalize_path() ` +For example, `ProjectSettings.globalize_path() ` can be used to open "local" paths in the OS file manager -using :ref:`OS.shell_open() ` since it only accepts +using `OS.shell_open() ` since it only accepts native OS paths. To convert an absolute OS path to a "local" path starting with ``res://`` -or ``user://``, use :ref:`ProjectSettings.localize_path() `. +or ``user://``, use `ProjectSettings.localize_path() `. This only works for absolute paths that point to files or folders in your project's root or ``user://`` folders. @@ -169,7 +169,7 @@ self-contained mode by default. Self-contained mode is not supported in exported projects yet. To read and write files relative to the executable path, use - :ref:`OS.get_executable_path() `. + `OS.get_executable_path() `. Note that writing files in the executable path only works if the executable is placed in a writable location (i.e. **not** Program Files or another directory that is read-only for regular users). diff --git a/tutorials/io/saving_games.rst b/tutorials/io/saving_games.rst index 824cd58..a3d6005 100644 --- a/tutorials/io/saving_games.rst +++ b/tutorials/io/saving_games.rst @@ -15,7 +15,7 @@ scale as the game grows more complex. .. note:: If you're looking to save user configuration, you can use the - :ref:`class_ConfigFile` class for this purpose. + `class_ConfigFile` class for this purpose. Identify persistent objects --------------------------- @@ -48,8 +48,8 @@ Serializing The next step is to serialize the data. This makes it much easier to read from and store to disk. In this case, we're assuming each member of group Persist is an instanced node and thus has a path. GDScript -has helper functions for this, such as :ref:`to_json() -` and :ref:`parse_json() +has helper functions for this, such as `to_json() +` and `parse_json() `, so we will use a dictionary. Our node needs to contain a save function that returns this data. The save function will look like this: @@ -89,9 +89,9 @@ loading. Saving and reading data ----------------------- -As covered in the :ref:`doc_filesystem` tutorial, we'll need to open a file +As covered in the `doc_filesystem` tutorial, we'll need to open a file so we can write to it or read from it. Now that we have a way to -call our groups and get their relevant data, let's use :ref:`to_json() +call our groups and get their relevant data, let's use `to_json() ` to convert it into an easily stored string and store them in a file. Doing it this way ensures that each line is its own object, so we have an easy @@ -188,8 +188,8 @@ customized based on the needs of the individual project. Additionally, our implementation assumes no Persist objects are children of other Persist objects. Otherwise, invalid paths would be created. To accommodate nested Persist objects, consider saving objects in stages. -Load parent objects first so they are available for the :ref:`add_child() +Load parent objects first so they are available for the `add_child() ` call when child objects are loaded. You will also need a way to link -children to parents as the :ref:`NodePath +children to parents as the `NodePath ` will likely be invalid. diff --git a/tutorials/math/beziers_and_curves.rst b/tutorials/math/beziers_and_curves.rst index 0499e42..2cbef9c 100644 --- a/tutorials/math/beziers_and_curves.rst +++ b/tutorials/math/beziers_and_curves.rst @@ -10,7 +10,7 @@ high level of flexibility. Unlike more abstract mathematical concepts, Bezier curves were created for industrial design. They are a popular tool in the graphics software industry. -They rely on :ref:`interpolation`, which we saw in the +They rely on `interpolation`, which we saw in the previous article, combining multiple steps to create smooth curves. To better understand how Bezier curves work, let's start from its simplest form: Quadratic Bezier. @@ -147,9 +147,9 @@ work and look in Godot. Curve2D, Curve3D, Path and Path2D --------------------------------- -There are two objects that contain curves: :ref:`Curve3D ` and :ref:`Curve2D ` (for 3D and 2D respectively). +There are two objects that contain curves: `Curve3D ` and `Curve2D ` (for 3D and 2D respectively). -They can contain several points, allowing for longer paths. It is also possible to set them to nodes: :ref:`Path ` and :ref:`Path2D ` (also for 3D and 2D respectively): +They can contain several points, allowing for longer paths. It is also possible to set them to nodes: `Path ` and `Path2D ` (also for 3D and 2D respectively): .. image:: img/bezier_path_2d.png @@ -190,15 +190,15 @@ Additionally, if both control points were ``0, 0`` (remember they are relative v Before drawing Bezier curves, *tessellation* is required. This is often done with a recursive or divide and conquer function that splits the curve until the curvature amount becomes less than a certain threshold. The *Curve* classes provide this via the -:ref:`Curve2D.tessellate() ` function (which receives optional ``stages`` of recursion and angle ``tolerance`` arguments). This way, drawing something based on a curve is easier. +`Curve2D.tessellate() ` function (which receives optional ``stages`` of recursion and angle ``tolerance`` arguments). This way, drawing something based on a curve is easier. Traversal --------- The last common use case for the curves is to traverse them. Because of what was mentioned before regarding constant speed, this is also difficult. -To make this easier, the curves need to be *baked* into equidistant points. This way, they can be approximated with regular interpolation (which can be improved further with a cubic option). To do this, just use the :ref:`Curve.interpolate_baked()` method together with -:ref:`Curve2D.get_baked_length()`. The first call to either of them will bake the curve internally. +To make this easier, the curves need to be *baked* into equidistant points. This way, they can be approximated with regular interpolation (which can be improved further with a cubic option). To do this, just use the `Curve.interpolate_baked()` method together with +`Curve2D.get_baked_length()`. The first call to either of them will bake the curve internally. Traversal at constant speed, then, can be done with the following pseudo-code: diff --git a/tutorials/math/interpolation.rst b/tutorials/math/interpolation.rst index b4c8187..3b5c670 100644 --- a/tutorials/math/interpolation.rst +++ b/tutorials/math/interpolation.rst @@ -23,15 +23,15 @@ And often simplified to: The name of this type of interpolation, which transforms a value into another at *constant speed* is *"linear"*. So, when you hear about *Linear Interpolation*, you know they are referring to this simple formula. -There are other types of interpolations, which will not be covered here. A recommended read afterwards is the :ref:`Bezier ` page. +There are other types of interpolations, which will not be covered here. A recommended read afterwards is the `Bezier ` page. Vector interpolation -------------------- -Vector types (:ref:`Vector2 ` and :ref:`Vector3 `) can also be interpolated, they come with handy functions to do it -:ref:`Vector2.linear_interpolate() ` and :ref:`Vector3.linear_interpolate() `. +Vector types (`Vector2 ` and `Vector3 `) can also be interpolated, they come with handy functions to do it +`Vector2.linear_interpolate() ` and `Vector3.linear_interpolate() `. -For cubic interpolation, there are also :ref:`Vector2.cubic_interpolate() ` and :ref:`Vector3.cubic_interpolate() `, which do a :ref:`Bezier ` style interpolation. +For cubic interpolation, there are also `Vector2.cubic_interpolate() ` and `Vector3.cubic_interpolate() `, which do a `Bezier ` style interpolation. Here is simple pseudo-code for going from point A to B using interpolation: @@ -54,7 +54,7 @@ Transform interpolation ----------------------- It is also possible to interpolate whole transforms (make sure they have either uniform scale or, at least, the same non-uniform scale). -For this, the function :ref:`Transform.interpolate_with() ` can be used. +For this, the function `Transform.interpolate_with() ` can be used. Here is an example of transforming a monkey from Position1 to Position2: diff --git a/tutorials/math/matrices_and_transforms.rst b/tutorials/math/matrices_and_transforms.rst index 23478ce..c1510f9 100644 --- a/tutorials/math/matrices_and_transforms.rst +++ b/tutorials/math/matrices_and_transforms.rst @@ -7,7 +7,7 @@ Introduction ------------ Before reading this tutorial, we recommend that you thoroughly read -and understand the :ref:`doc_vector_math` tutorial, as this tutorial +and understand the `doc_vector_math` tutorial, as this tutorial requires a knowledge of vectors. This tutorial is about *transformations* and how we represent them @@ -15,8 +15,8 @@ in Godot using matrices. It is not a full in-depth guide to matrices. Transformations are most of the time applied as translation, rotation, and scale, so we will focus on how to represent those with matrices. -Most of this guide focuses on 2D, using :ref:`class_Transform2D` and -:ref:`class_Vector2`, but the way things work in 3D is very similar. +Most of this guide focuses on 2D, using `class_Transform2D` and +`class_Vector2`, but the way things work in 3D is very similar. .. note:: As mentioned in the previous tutorial, it is important to remember that in Godot, the Y axis points *down* in 2D. @@ -175,19 +175,19 @@ are in charge of representing rotation, scale, and/or shearing called the *basis* of the transformation matrix. The terms "basis" and "basis vectors" are important to know. -You might have noticed that :ref:`class_Transform2D` actually -has three :ref:`class_Vector2` values: `x`, `y`, and `origin`. +You might have noticed that `class_Transform2D` actually +has three `class_Vector2` values: `x`, `y`, and `origin`. The `origin` value is not part of the basis, but it is part of the transform, and we need it to represent position. From now on we'll keep track of the origin vector in all examples. You can think of origin as another column, but it's often better to think of it as completely separate. -Note that in 3D, Godot has a separate :ref:`class_Basis` structure -for holding the three :ref:`class_Vector3` values of the basis, +Note that in 3D, Godot has a separate `class_Basis` structure +for holding the three `class_Vector3` values of the basis, since the code can get complex and it makes sense to separate -it from :ref:`class_Transform` (which is composed of one -:ref:`class_Basis` and one extra :ref:`class_Vector3` for the origin). +it from `class_Transform` (which is composed of one +`class_Basis` and one extra `class_Vector3` for the origin). Translating the transformation matrix ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -257,7 +257,7 @@ Shearing the transformation matrix (advanced) You may have noticed that a transform has more degrees of freedom than the combination of the above actions. The basis of a 2D transformation -matrix has four total numbers in two :ref:`class_Vector2` values, while +matrix has four total numbers in two `class_Vector2` values, while a rotation value and a Vector2 for scale only has 3 numbers. The high-level concept for the missing degree of freedom is called *shearing*. @@ -330,12 +330,12 @@ Practical applications of transforms ------------------------------------ In actual projects, you will usually be working with transforms inside -transforms by having multiple :ref:`class_Node2D` or :ref:`class_Spatial` +transforms by having multiple `class_Node2D` or `class_Spatial` nodes parented to each other. However, sometimes it's very useful to manually calculate the values we -need. We will go over how you could use :ref:`class_Transform2D` or -:ref:`class_Transform` to manually calculate transforms of nodes. +need. We will go over how you could use `class_Transform2D` or +`class_Transform` to manually calculate transforms of nodes. Converting positions between transforms ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -502,8 +502,8 @@ One of the great things about transformation matrices is that they work very similarly between 2D and 3D transformations. All the code and formulas used above for 2D work the same in 3D, with 3 exceptions: the addition of a third axis, that each -axis is of type :ref:`class_Vector3`, and also that Godot stores -the :ref:`class_Basis` separately from the :ref:`class_Transform`, +axis is of type `class_Vector3`, and also that Godot stores +the `class_Basis` separately from the `class_Transform`, since the math can get complex and it makes sense to separate it. All of the concepts for how translation, rotation, scale, and shearing @@ -518,7 +518,7 @@ If you would like, it's a good idea to play around with transforms to get an understanding of how they work. Godot allows you to edit 3D transform matrices directly from the inspector. You can download this project which has colored lines and cubes to help visualize the -:ref:`class_Basis` vectors and the origin in both 2D and 3D: +`class_Basis` vectors and the origin in both 2D and 3D: https://github.com/godotengine/godot-demo-projects/tree/master/misc/matrix_transform .. note:: Spatial's "Matrix" section in Godot 3.2's inspector @@ -547,7 +547,7 @@ useful, except for trivial cases. In 3D we do not typically use angles, we either use a transformation basis (used pretty much everywhere in Godot), or we use quaternions. Godot can -represent quaternions using the :ref:`class_Quat` struct. My suggestion +represent quaternions using the `class_Quat` struct. My suggestion to you is to completely ignore how they work under-the-hood, because they are very complicated and unintuitive. diff --git a/tutorials/math/random_number_generation.rst b/tutorials/math/random_number_generation.rst index 44e865f..918e12e 100644 --- a/tutorials/math/random_number_generation.rst +++ b/tutorials/math/random_number_generation.rst @@ -21,13 +21,13 @@ Global scope versus RandomNumberGenerator class ----------------------------------------------- Godot exposes two ways to generate random numbers: via *global scope* methods or -using the :ref:`class_RandomNumberGenerator` class. +using the `class_RandomNumberGenerator` class. Global scope methods are easier to set up, but they don't offer as much control. RandomNumberGenerator requires more code to use, but exposes many methods not -found in global scope such as :ref:`randi_range() -` and :ref:`randfn() +found in global scope such as `randi_range() +` and `randfn() `. On top of that, it allows creating multiple instances each with their own seed. @@ -37,7 +37,7 @@ the RandomNumberGenerator class. The randomize() method ---------------------- -In global scope, you can find a :ref:`randomize() +In global scope, you can find a `randomize() ` method. **This method should be called only once when your project starts to initialize the random seed.** Calling it multiple times is unnecessary and may impact performance negatively. @@ -51,7 +51,7 @@ gdscript GDScript randomize() ``` -You can also set a fixed random seed instead using :ref:`seed() +You can also set a fixed random seed instead using `seed() `. Doing so will give you *deterministic* results across runs: @@ -81,7 +81,7 @@ Getting a random number Let's look at some of the most commonly used functions and methods to generate random numbers in Godot. -The function :ref:`randi() ` returns a random +The function `randi() ` returns a random number between 0 and 2^32-1. Since the maximum value is huge, you most likely want to use the modulo operator (``%``) to bound the result between 0 and the denominator: @@ -97,12 +97,12 @@ gdscript GDScript ``` -:ref:`randf() ` returns a random floating-point +`randf() ` returns a random floating-point number between 0 and 1. This is useful to implement a -:ref:`doc_random_number_generation_weighted_random_probability` system, among +`doc_random_number_generation_weighted_random_probability` system, among other things. -:ref:`randfn() ` returns a random +`randfn() ` returns a random floating-point number following a `normal distribution `__. This means the returned value is more likely to be around the mean (0.0 by default), @@ -117,7 +117,7 @@ gdscript GDScript print(random.randfn()) ``` -:ref:`rand_range() ` takes two arguments +`rand_range() ` takes two arguments ``from`` and ``to``, and returns a random floating-point number between ``from`` and ``to``: @@ -128,7 +128,7 @@ gdscript GDScript print(rand_range(-4, 6.5)) ``` -:ref:`RandomNumberGenerator.randi_range() +`RandomNumberGenerator.randi_range() ` takes two arguments ``from`` and ``to``, and returns a random integer between ``from`` and ``to``: @@ -202,7 +202,7 @@ gdscript GDScript This approach can be useful to make random number generation feel less repetitive. Still, it doesn't prevent results from "ping-ponging" between a -limited set of values. To prevent this, use the :ref:`shuffle bag +limited set of values. To prevent this, use the `shuffle bag ` pattern instead. Get a random dictionary value @@ -239,7 +239,7 @@ gdscript GDScript Weighted random probability --------------------------- -The :ref:`randf() ` method returns a +The `randf() ` method returns a floating-point number between 0.0 and 1.0. We can use this to create a "weighted" probability where different outcomes have different likelihoods: @@ -321,7 +321,7 @@ time, or anything else. To achieve this, you can use random *noise* functions. Noise functions are especially popular in procedural generation to generate realistic-looking -terrain. Godot provides :ref:`class_opensimplexnoise` for this, which supports +terrain. Godot provides `class_opensimplexnoise` for this, which supports 1D, 2D, 3D, and 4D noise. Here's an example with 1D noise: gdscript GDScript diff --git a/tutorials/math/vector_math.rst b/tutorials/math/vector_math.rst index f64ad62..15ebcd8 100644 --- a/tutorials/math/vector_math.rst +++ b/tutorials/math/vector_math.rst @@ -69,8 +69,8 @@ gdscript GDScript $Node2D.position = Vector2(400, 300) ``` -Godot supports both :ref:`Vector2 ` and -:ref:`Vector3 ` for 2D and 3D usage, respectively. The same +Godot supports both `Vector2 ` and +`Vector3 ` for 2D and 3D usage, respectively. The same mathematical rules discussed in this article apply to both types. Member access @@ -199,9 +199,9 @@ wall or other object: The surface normal has a value of ``(0, -1)`` because this is a horizontal surface. When the ball collides, we take its remaining motion (the amount left over when it hits the surface) and reflect it using the normal. In -Godot, the :ref:`Vector2 ` class has a ``bounce()`` method +Godot, the `Vector2 ` class has a ``bounce()`` method to handle this. Here is a GDScript example of the diagram above using a -:ref:`KinematicBody2D `: +`KinematicBody2D `: gdscript GDScript @@ -348,5 +348,5 @@ More information For more information on using vector math in Godot, see the following articles: -- :ref:`doc_vectors_advanced` -- :ref:`doc_matrices_and_transforms` +- `doc_vectors_advanced` +- `doc_matrices_and_transforms` diff --git a/tutorials/math/vectors_advanced.rst b/tutorials/math/vectors_advanced.rst index 8a56e46..8b69505 100644 --- a/tutorials/math/vectors_advanced.rst +++ b/tutorials/math/vectors_advanced.rst @@ -67,7 +67,7 @@ by N and D. For example: .. image:: img/tutovec12.png -For 3D math, Godot provides a :ref:`Plane ` +For 3D math, Godot provides a `Plane ` built-in type that handles this. Basically, N and D can represent any plane in space, be it for 2D or 3D @@ -114,7 +114,7 @@ gdscript GDScript D = -D ``` -Of course, Godot also implements this operator in :ref:`Plane `, +Of course, Godot also implements this operator in `Plane `, so doing: gdscript GDScript @@ -382,7 +382,7 @@ More information For more information on using vector math in Godot, see the following article: -- :ref:`doc_matrices_and_transforms` +- `doc_matrices_and_transforms` If you would like additional explanation, you should check out 3Blue1Brown's excellent video series "Essence of Linear Algebra": diff --git a/tutorials/navigation/real_time_navigation_3d.rst b/tutorials/navigation/real_time_navigation_3d.rst index f272e49..018069e 100644 --- a/tutorials/navigation/real_time_navigation_3d.rst +++ b/tutorials/navigation/real_time_navigation_3d.rst @@ -10,10 +10,10 @@ Pathfinding in a 3D environment is crucial for many games, it's commonly how non directly controlled characters or entities find their way around an environment. Godot provides several nodes for this purpose: -- :ref:`Navigation` (deprecated) -- :ref:`NavigationMeshInstance` -- :ref:`NavigationAgent` -- :ref:`NavigationObstacle` +- `Navigation` (deprecated) +- `NavigationMeshInstance` +- `NavigationAgent` +- `NavigationObstacle` The map and navigation regions ------------------------------ @@ -23,12 +23,12 @@ the physics engine. It's comprised of navigation regions, these regions define parts of the world that can be navigated around by navigation agents. -To create a navigation region add the :ref:`NavigationMeshInstance` +To create a navigation region add the `NavigationMeshInstance` node to a 3D scene. Next in the inspector for that mesh create or add a -:ref:`NavigationMesh`. The navmesh contains options +`NavigationMesh`. The navmesh contains options for how it will be generated when it's baked. The geometry options control which nodes, and types of nodes, are used to bake the mesh. A full -description of each setting and how it works can be found in the :ref:`NavigationMesh class reference`. +description of each setting and how it works can be found in the `NavigationMesh class reference`. Once the settings have been properly configured press the "Bake NavMesh" button at the top of the inspector to generate it. @@ -79,7 +79,7 @@ with `set_velocity`. Then a new velocity that takes into account other agents and obstacles is generated and emitted with the signal `velocity_computed`. However agents can only take into account a set number of other nearby -agents, this is the :ref:`max neighbors` +agents, this is the `max neighbors` property of an agent and can be adjusted. This is **not** a limit for how many agents can use a navigation region at the same time. @@ -106,6 +106,6 @@ starting location, the next is a Vector3 of the end location. And the last argument is a boolean for whether or not agent properties of a navmesh are considered when generating a path. -The method will return a :ref:`PoolVector3Array ` consisting of +The method will return a `PoolVector3Array ` consisting of points that make a path. If there is no way to navigate to the end -location the method will return a blank :ref:`PoolVector3Array `. +location the method will return a blank `PoolVector3Array `. diff --git a/tutorials/networking/high_level_multiplayer.rst b/tutorials/networking/high_level_multiplayer.rst index 52a101f..4b2a8ef 100644 --- a/tutorials/networking/high_level_multiplayer.rst +++ b/tutorials/networking/high_level_multiplayer.rst @@ -23,7 +23,7 @@ This is due to the inherent limitations of the low-level protocols: In general, TCP can be thought of as reliable, ordered, and slow; UDP as unreliable, unordered and fast. Because of the large difference in performance, it often makes sense to re-build the parts of TCP wanted for games (optional reliability and packet order), while avoiding the unwanted parts (congestion/traffic control features, Nagle's algorithm, etc). Due to this, most game engines come with such an implementation, and Godot is no exception. -In summary, you can use the low-level networking API for maximum control and implement everything on top of bare network protocols or use the high-level API based on :ref:`SceneTree ` that does most of the heavy lifting behind the scenes in a generally optimized way. +In summary, you can use the low-level networking API for maximum control and implement everything on top of bare network protocols or use the high-level API based on `SceneTree ` that does most of the heavy lifting behind the scenes in a generally optimized way. .. note:: Most of Godot's supported platforms offer all or most of the mentioned high- and low-level networking features. As networking is always largely hardware and operating system dependent, however, @@ -56,15 +56,15 @@ Mid level abstraction Before going into how we would like to synchronize a game across the network, it can be helpful to understand how the base network API for synchronization works. -Godot uses a mid-level object :ref:`NetworkedMultiplayerPeer `. +Godot uses a mid-level object `NetworkedMultiplayerPeer `. This object is not meant to be created directly, but is designed so that several C++ implementations can provide it. -This object extends from :ref:`PacketPeer `, so it inherits all the useful methods for serializing, sending and receiving data. On top of that, it adds methods to set a peer, transfer mode, etc. It also includes signals that will let you know when peers connect or disconnect. +This object extends from `PacketPeer `, so it inherits all the useful methods for serializing, sending and receiving data. On top of that, it adds methods to set a peer, transfer mode, etc. It also includes signals that will let you know when peers connect or disconnect. This class interface can abstract most types of network layers, topologies and libraries. By default, Godot -provides an implementation based on ENet (:ref:`NetworkedMultiplayerEnet `), -one based on WebRTC (:ref:`WebRTCMultiplayer `), and one based on WebSocket -(:ref:`WebSocketMultiplayerPeer `), but this could be used to implement +provides an implementation based on ENet (`NetworkedMultiplayerEnet `), +one based on WebRTC (`WebRTCMultiplayer `), and one based on WebSocket +(`WebSocketMultiplayerPeer `), but this could be used to implement mobile APIs (for ad hoc WiFi, Bluetooth) or custom device/console-specific networking APIs. For most common cases, using this object directly is discouraged, as Godot provides even higher level networking facilities. @@ -73,7 +73,7 @@ Yet it is made available in case a game has specific needs for a lower level API Initializing the network ------------------------ -The object that controls networking in Godot is the same one that controls everything tree-related: :ref:`SceneTree `. +The object that controls networking in Godot is the same one that controls everything tree-related: `SceneTree `. To initialize high-level networking, the SceneTree must be provided a NetworkedMultiplayerPeer object. @@ -126,7 +126,7 @@ Managing connections -------------------- Some games accept connections at any time, others during the lobby phase. Godot can be requested to no longer accept -connections at any point (see ``set_refuse_new_network_connections(bool)`` and related methods on :ref:`SceneTree `). To manage who connects, Godot provides the following signals in SceneTree: +connections at any point (see ``set_refuse_new_network_connections(bool)`` and related methods on `SceneTree `). To manage who connects, Godot provides the following signals in SceneTree: Server and Clients: @@ -136,7 +136,7 @@ Server and Clients: The above signals are called on every peer connected to the server (including on the server) when a new peer connects or disconnects. Clients will connect with a unique ID greater than 1, while network peer ID 1 is always the server. Anything below 1 should be handled as invalid. -You can retrieve the ID for the local system via :ref:`SceneTree.get_network_unique_id() `. +You can retrieve the ID for the local system via `SceneTree.get_network_unique_id() `. These IDs will be useful mostly for lobby management and should generally be stored, as they identify connected peers and thus players. You can also use IDs to send messages only to certain peers. Clients: @@ -156,7 +156,7 @@ RPC --- To communicate between peers, the easiest way is to use RPCs (remote procedure calls). This is implemented as a set of functions -in :ref:`Node `: +in `Node `: - ``rpc("function_name", )`` - ``rpc_id(,"function_name", )`` @@ -178,7 +178,7 @@ Functions can be called in two fashions: In most cases, reliable is desired. Unreliable is mostly useful when synchronizing object positions (sync must happen constantly, and if a packet is lost, it's not that bad because a new one will eventually arrive and it would likely be outdated because the object moved further in the meantime, even if it was resent reliably). -There is also :ref:`SceneTree.get_rpc_sender_id() `, which can be used to check which peer (or peer ID) sent an RPC. +There is also `SceneTree.get_rpc_sender_id() `, which can be used to check which peer (or peer ID) sent an RPC. Back to lobby ------------- @@ -260,9 +260,9 @@ If ``sync`` is included, the call can also be made locally. For example, to allo puppetsync func update_position(new_position): position = new_position -.. tip:: You can also use :ref:`SceneTree.get_rpc_sender_id() ` to have more advanced rules on how an rpc can be called. +.. tip:: You can also use `SceneTree.get_rpc_sender_id() ` to have more advanced rules on how an rpc can be called. -These keywords are further explained in :ref:`Synchronizing the game `. +These keywords are further explained in `Synchronizing the game `. With this, lobby management should be more or less explained. Once you have your game going, you will most likely want to add some extra security to make sure clients don't do anything funny (just validate the info they send from time to time, or before @@ -367,9 +367,9 @@ The network master of a node is the peer that has the ultimate authority over it When not explicitly set, the network master is inherited from the parent node, which if not changed, is always going to be the server (ID 1). Thus the server has authority over all nodes by default. The network master can be set -with the function :ref:`Node.set_network_master(id, recursive) ` (recursive is ``true`` by default and means the network master is recursively set on all child nodes of the node as well). +with the function `Node.set_network_master(id, recursive) ` (recursive is ``true`` by default and means the network master is recursively set on all child nodes of the node as well). -Checking that a specific node instance on a peer is the network master for this node for all connected peers is done by calling :ref:`Node.is_network_master() `. This will return ``true`` when executed on the server and ``false`` on all client peers. +Checking that a specific node instance on a peer is the network master for this node for all connected peers is done by calling `Node.is_network_master() `. This will return ``true`` when executed on the server and ``false`` on all client peers. If you have paid attention to the previous example, it's possible you noticed that each peer was set to have network master authority for their own player (Node) instead of the server: @@ -474,7 +474,7 @@ Exporting for dedicated servers Once you've made a multiplayer game, you may want to export it to run it on a dedicated server with no GPU available. See -:ref:`doc_exporting_for_dedicated_servers` for more information. +`doc_exporting_for_dedicated_servers` for more information. .. note:: diff --git a/tutorials/networking/http_client_class.rst b/tutorials/networking/http_client_class.rst index 233ceec..f2e7587 100644 --- a/tutorials/networking/http_client_class.rst +++ b/tutorials/networking/http_client_class.rst @@ -3,9 +3,9 @@ HTTP client class ================= -:ref:`HTTPClient ` provides low-level access to HTTP communication. -For a higher-level interface, you may want to take a look at :ref:`HTTPRequest ` first, -which has a tutorial available :ref:`here `. +`HTTPClient ` provides low-level access to HTTP communication. +For a higher-level interface, you may want to take a look at `HTTPRequest ` first, +which has a tutorial available `here `. .. warning:: @@ -14,7 +14,7 @@ which has a tutorial available :ref:`here `. using one-click deploy. Otherwise, network communication of any kind will be blocked by Android. -Here's an example of using the :ref:`HTTPClient ` +Here's an example of using the `HTTPClient ` class. It's just a script, so it can be run by executing: console GDScript diff --git a/tutorials/networking/http_request_class.rst b/tutorials/networking/http_request_class.rst index 9f72669..ea1c48c 100644 --- a/tutorials/networking/http_request_class.rst +++ b/tutorials/networking/http_request_class.rst @@ -3,8 +3,8 @@ Making HTTP requests ==================== -The :ref:`HTTPRequest ` node is the easiest way to make HTTP requests in Godot. -It is backed by the more low-level :ref:`HTTPClient `, for which a tutorial is available :ref:`here `. +The `HTTPRequest ` node is the easiest way to make HTTP requests in Godot. +It is backed by the more low-level `HTTPClient `, for which a tutorial is available `here `. For the sake of this example, we will create a simple UI with a button, that when pressed will start the HTTP request to the specified URL. @@ -48,9 +48,9 @@ gdscript GDScript With this, you should see ``(hello:world)`` printed on the console; hello being a key, and world being a value, both of them strings. -For more information on parsing JSON, see the class references for :ref:`JSON ` and :ref:`JSONParseResult `. +For more information on parsing JSON, see the class references for `JSON ` and `JSONParseResult `. -Note that you may want to check whether the ``result`` equals ``RESULT_SUCCESS`` and whether a JSON parsing error occurred, see the JSON class reference and :ref:`HTTPRequest ` for more. +Note that you may want to check whether the ``result`` equals ``RESULT_SUCCESS`` and whether a JSON parsing error occurred, see the JSON class reference and `HTTPRequest ` for more. Of course, you can also set custom HTTP headers. These are given as a string array, with each string containing a header in the format ``"header: value"``. For example, to set a custom user agent (the HTTP ``user-agent`` header) you could use the following: @@ -61,7 +61,7 @@ gdscript GDScript $HTTPRequest.request("http://www.mocky.io/v2/5185415ba171ea3a00704eed", ["user-agent: YourCustomUserAgent"]) ``` -Please note that, for SSL/TLS encryption and thus HTTPS URLs to work, you may need to take some steps as described :ref:`here `. +Please note that, for SSL/TLS encryption and thus HTTPS URLs to work, you may need to take some steps as described `here `. Also, when calling APIs using authorization, be aware that someone might analyse and decompile your released application and thus may gain access to any embedded authorization information like tokens, usernames or passwords. That means it is usually not a good idea to embed things such as database access credentials inside your game. Avoid providing information useful to an attacker whenever possible. diff --git a/tutorials/networking/ssl_certificates.rst b/tutorials/networking/ssl_certificates.rst index fe951e2..574bb33 100644 --- a/tutorials/networking/ssl_certificates.rst +++ b/tutorials/networking/ssl_certificates.rst @@ -8,9 +8,9 @@ Introduction It is often desired to use SSL connections for communications to avoid "man in the middle" attacks. Godot has a connection wrapper, -:ref:`StreamPeerSSL `, +`StreamPeerSSL `, which can take a regular connection and add security around it. The -:ref:`HTTPClient ` +`HTTPClient ` class also supports HTTPS by using this same wrapper. Godot includes SSL certificates from Mozilla, but you can provide your own diff --git a/tutorials/networking/webrtc.rst b/tutorials/networking/webrtc.rst index a49eb5a..c08d925 100644 --- a/tutorials/networking/webrtc.rst +++ b/tutorials/networking/webrtc.rst @@ -33,7 +33,7 @@ Peers connect to a signaling server (for example a WebSocket server) and send th Using WebRTC in Godot --------------------- -WebRTC is implemented in Godot via two main classes :ref:`WebRTCPeerConnection ` and :ref:`WebRTCDataChannel `, plus the multiplayer API implementation :ref:`WebRTCMultiplayer `. See section on :ref:`high-level multiplayer ` for more details. +WebRTC is implemented in Godot via two main classes `WebRTCPeerConnection ` and `WebRTCDataChannel `, plus the multiplayer API implementation `WebRTCMultiplayer `. See section on `high-level multiplayer ` for more details. .. note:: These classes are available automatically in HTML5, but **require an external GDNative plugin on native (non-HTML5) platforms**. Check out the `webrtc-native plugin repository `__ for instructions and to get the latest `release `__. @@ -105,7 +105,7 @@ This will print: Local signaling example ^^^^^^^^^^^^^^^^^^^^^^^ -This example expands on the previous one, separating the peers in two different scenes, and using a :ref:`singleton ` as a signaling server. +This example expands on the previous one, separating the peers in two different scenes, and using a `singleton ` as a signaling server. :: @@ -147,7 +147,7 @@ This example expands on the previous one, separating the peers in two different And now for the local signaling server: -.. note:: This local signaling server is supposed to be used as a :ref:`singleton ` to connect two peers in the same scene. +.. note:: This local signaling server is supposed to be used as a `singleton ` to connect two peers in the same scene. :: @@ -212,4 +212,4 @@ This will print something similar to this: Remote signaling with WebSocket ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -A more advanced demo using WebSocket for signaling peers and :ref:`WebRTCMultiplayer ` is available in the `godot demo projects `_ under `networking/webrtc_signaling`. +A more advanced demo using WebSocket for signaling peers and `WebRTCMultiplayer ` is available in the `godot demo projects `_ under `networking/webrtc_signaling`. diff --git a/tutorials/networking/websocket.rst b/tutorials/networking/websocket.rst index 78af112..e9fc3e0 100644 --- a/tutorials/networking/websocket.rst +++ b/tutorials/networking/websocket.rst @@ -9,7 +9,7 @@ HTML5 and WebSocket The WebSocket protocol was standardized in 2011 with the original goal of allowing browsers to create stable and bidirectional connections with a server. Before that, browsers used to only support HTTPRequests, which is not well-suited for bidirectional communication. -The protocol is quite simple, message based, and a very powerful tool to send push notifications to browsers, and has been used to implement chats, turn-based games, etc. It still uses a TCP connection, which is good for reliability but not for latency, so not good for real-time applications like VoIP and fast-paced games (see :ref:`WebRTC ` for those use cases). +The protocol is quite simple, message based, and a very powerful tool to send push notifications to browsers, and has been used to implement chats, turn-based games, etc. It still uses a TCP connection, which is good for reliability but not for latency, so not good for real-time applications like VoIP and fast-paced games (see `WebRTC ` for those use cases). Due to its simplicity, its wide compatibility, and being easier to use than a raw TCP connection, WebSocket soon started to spread outside the browsers, in native applications as a mean to communicate with network servers. @@ -18,7 +18,7 @@ Godot supports WebSocket in both native and HTML5 exports. Using WebSocket in Godot ------------------------ -WebSocket is implemented in Godot via three main classes :ref:`WebSocketClient `, :ref:`WebSocketServer `, and :ref:`WebSocketPeer `. The WebSocket implementation is compatible with the High Level Multiplayer. See section on :ref:`high-level multiplayer ` for more details. +WebSocket is implemented in Godot via three main classes `WebSocketClient `, `WebSocketServer `, and `WebSocketPeer `. The WebSocket implementation is compatible with the High Level Multiplayer. See section on `high-level multiplayer ` for more details. .. warning:: diff --git a/tutorials/performance/batching.rst b/tutorials/performance/batching.rst index 334d1d3..b1d3c45 100644 --- a/tutorials/performance/batching.rst +++ b/tutorials/performance/batching.rst @@ -93,14 +93,14 @@ In Godot, this back-to-front order is determined by: - The order of objects in the scene tree. - The Z index of objects. - The canvas layer. -- :ref:`class_YSort` nodes. +- `class_YSort` nodes. .. note:: You can group similar objects together for easier batching. While doing so is not a requirement on your part, think of it as an optional approach that can improve performance in some cases. See the - :ref:`doc_batching_diagnostics` section to help you make this decision. + `doc_batching_diagnostics` section to help you make this decision. A trick ^^^^^^^ @@ -230,7 +230,7 @@ any pixels. We can greatly optimize fill rate by identifying the intersection area between a light and a primitive, and limit rendering the light to *that area only*. -Light scissoring is controlled with the :ref:`scissor_area_threshold +Light scissoring is controlled with the `scissor_area_threshold ` project setting. This value is between 1.0 and 0.0, with 1.0 being off (no scissoring), and 0.0 being scissoring in every circumstance. The reason for the @@ -248,7 +248,7 @@ to be useful. The exact relationship is probably not necessary for users to worry about, but is included in the appendix out of interest: -:ref:`doc_batching_light_scissoring_threshold_calculation` +`doc_batching_light_scissoring_threshold_calculation` .. figure:: img/scissoring.png :alt: Light scissoring example diagram @@ -307,16 +307,16 @@ information. rendering/batching/options ^^^^^^^^^^^^^^^^^^^^^^^^^^ -- :ref:`use_batching +- `use_batching ` - Turns batching on or off. -- :ref:`use_batching_in_editor +- `use_batching_in_editor ` Turns batching on or off in the Godot editor. This setting doesn't affect the running project in any way. -- :ref:`single_rect_fallback +- `single_rect_fallback ` - This is a faster way of drawing unbatchable rectangles. However, it may lead to flicker on some hardware so it's not recommended. @@ -324,7 +324,7 @@ rendering/batching/options rendering/batching/parameters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -- :ref:`max_join_item_commands ` - +- `max_join_item_commands ` - One of the most important ways of achieving batching is to join suitable adjacent items (nodes) together, however they can only be joined if the commands they contain are compatible. The system must therefore do a lookahead @@ -332,7 +332,7 @@ rendering/batching/parameters has a small cost per command, and items with a large number of commands are not worth joining, so the best value may be project dependent. -- :ref:`colored_vertex_format_threshold +- `colored_vertex_format_threshold ` - Baking colors into vertices results in a larger vertex format. This is not necessarily worth doing unless there are a lot of color changes going on @@ -340,12 +340,12 @@ rendering/batching/parameters containing color changes / the total commands, above which it switches to baked colors. -- :ref:`batch_buffer_size +- `batch_buffer_size ` - This determines the maximum size of a batch, it doesn't have a huge effect on performance but can be worth decreasing for mobile if RAM is at a premium. -- :ref:`item_reordering_lookahead +- `item_reordering_lookahead ` - Item reordering can help especially with interleaved sprites using different textures. The lookahead for the overlap test has a small cost, so the best @@ -354,11 +354,11 @@ rendering/batching/parameters rendering/batching/lights ^^^^^^^^^^^^^^^^^^^^^^^^^ -- :ref:`scissor_area_threshold +- `scissor_area_threshold ` - See light scissoring. -- :ref:`max_join_items +- `max_join_items ` - Joining items before lighting can significantly increase performance. This requires an overlap test, which has a small cost, so the @@ -368,14 +368,14 @@ rendering/batching/lights rendering/batching/debug ^^^^^^^^^^^^^^^^^^^^^^^^ -- :ref:`flash_batching +- `flash_batching ` - This is purely a debugging feature to identify regressions between the batching and legacy renderer. When it is switched on, the batching and legacy renderer are used alternately on each frame. This will decrease performance, and should not be used for your final export, only for testing. -- :ref:`diagnose_frame +- `diagnose_frame ` - This will periodically print a diagnostic batching log to the Godot IDE / console. @@ -383,7 +383,7 @@ rendering/batching/debug rendering/batching/precision ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -- :ref:`uv_contract +- `uv_contract ` - On some hardware (notably some Android devices) there have been reports of tilemap tiles drawing slightly outside their UV range, leading to edge @@ -391,7 +391,7 @@ rendering/batching/precision contract. This makes a small contraction in the UV coordinates to compensate for precision errors on devices. -- :ref:`uv_contract_amount +- `uv_contract_amount ` - Hopefully, the default amount should cure artifacts on most devices, but this value remains adjustable just in case. @@ -485,7 +485,7 @@ I get a decrease in performance with batching. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Try the steps described above to increase the number of batching opportunities. -- Try enabling :ref:`single_rect_fallback +- Try enabling `single_rect_fallback `. - The single rect fallback method is the default used without batching, and it is approximately twice as fast. However, it can result in flickering on some @@ -501,7 +501,7 @@ I use custom shaders and the items are not batching. I am seeing line artifacts appear on certain hardware. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -- See the :ref:`uv_contract +- See the `uv_contract ` project setting which can be used to solve this problem. @@ -528,7 +528,7 @@ primitive types are currently available: With non-batched primitives, you may be able to get better performance by drawing them manually with polys in a ``_draw()`` function. -See :ref:`doc_custom_drawing_in_2d` for more information. +See `doc_custom_drawing_in_2d` for more information. .. _doc_batching_light_scissoring_threshold_calculation: @@ -536,7 +536,7 @@ Light scissoring threshold calculation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The actual proportion of screen pixel area used as the threshold is the -:ref:`scissor_area_threshold +`scissor_area_threshold ` value to the power of 4. @@ -547,11 +547,11 @@ At a threshold of 1,000 pixels, the proportion would be:: 1000 / 2073600 = 0.00048225 0.00048225 ^ (1/4) = 0.14819 -So a :ref:`scissor_area_threshold +So a `scissor_area_threshold ` of ``0.15`` would be a reasonable value to try. -Going the other way, for instance with a :ref:`scissor_area_threshold +Going the other way, for instance with a `scissor_area_threshold ` of ``0.5``:: diff --git a/tutorials/performance/cpu_optimization.rst b/tutorials/performance/cpu_optimization.rst index cf335ca..0542ff9 100644 --- a/tutorials/performance/cpu_optimization.rst +++ b/tutorials/performance/cpu_optimization.rst @@ -46,7 +46,7 @@ process taking a lot more time than others. This is your primary bottleneck, and you can usually increase speed by optimizing this area. For more info about using Godot's built-in profiler, see -:ref:`doc_debugger_panel`. +`doc_debugger_panel`. External profilers ~~~~~~~~~~~~~~~~~~ @@ -154,7 +154,7 @@ will be able to work as fast as possible. Godot usually takes care of such low-level details for you. For example, the Server APIs make sure data is optimized for caching already for things like rendering and physics. Still, you should be especially aware of caching when -using :ref:`GDNative `. +using `GDNative `. Languages ========= @@ -170,7 +170,7 @@ code, consider moving those calculations to a faster language. GDScript ~~~~~~~~ -:ref:`GDScript ` is designed to be easy to use and iterate, +`GDScript ` is designed to be easy to use and iterate, and is ideal for making many types of games. However, in this language, ease of use is considered more important than performance. If you need to make heavy calculations, consider moving some of your project to one of the other @@ -179,7 +179,7 @@ languages. C# ~~ -:ref:`C# ` is popular and has first-class support in Godot.It +`C# ` is popular and has first-class support in Godot.It offers a good compromise between speed and ease of use. Beware of possible garbage collection pauses and leaks that can occur during gameplay, though. A common approach to workaround issues with garbage collection is to use *object @@ -198,8 +198,8 @@ C++ Godot is written in C++. Using C++ will usually result in the fastest code. However, on a practical level, it is the most difficult to deploy to end users' machines on different platforms. Options for using C++ include -:ref:`GDNative ` and -:ref:`custom modules `. +`GDNative ` and +`custom modules `. Threads ======= @@ -218,7 +218,7 @@ you understand the dangers and how to try and prevent these race conditions. Threads can also make debugging considerably more difficult. The GDScript debugger doesn't support setting up breakpoints in threads yet. -For more information on threads, see :ref:`doc_using_multiple_threads`. +For more information on threads, see `doc_using_multiple_threads`. SceneTree ========= @@ -231,16 +231,16 @@ performance when you have very large numbers of nodes (usually in the thousands) Each node is handled individually in the Godot renderer. Therefore, a smaller number of nodes with more in each can lead to better performance. -One quirk of the :ref:`SceneTree ` is that you can sometimes +One quirk of the `SceneTree ` is that you can sometimes get much better performance by removing nodes from the SceneTree, rather than by pausing or hiding them. You don't have to delete a detached node. You can for example, keep a reference to a node, detach it from the scene tree using -:ref:`Node.remove_child(node) `, then reattach -it later using :ref:`Node.add_child(node) `. +`Node.remove_child(node) `, then reattach +it later using `Node.add_child(node) `. This can be very useful for adding and removing areas from a game, for example. You can avoid the SceneTree altogether by using Server APIs. For more -information, see :ref:`doc_using_servers`. +information, see `doc_using_servers`. Physics ======= diff --git a/tutorials/performance/general_optimization.rst b/tutorials/performance/general_optimization.rst index 71536d5..f7df706 100644 --- a/tutorials/performance/general_optimization.rst +++ b/tutorials/performance/general_optimization.rst @@ -128,7 +128,7 @@ of your improvements. Sometimes, attempts to improve performance can backfire and lead to slower performance. **Always use profiling and timing to guide your efforts.** -For more info about using Godot's built-in profiler, see :ref:`doc_debugger_panel`. +For more info about using Godot's built-in profiler, see `doc_debugger_panel`. Principles ========== diff --git a/tutorials/performance/gpu_optimization.rst b/tutorials/performance/gpu_optimization.rst index 42492ee..4cca97e 100644 --- a/tutorials/performance/gpu_optimization.rst +++ b/tutorials/performance/gpu_optimization.rst @@ -51,7 +51,7 @@ via a single draw call, rather than making a separate draw call for each item. In addition, this means state changes, material and texture changes can be kept to a minimum. -For more information on 2D batching, see :ref:`doc_batching`. +For more information on 2D batching, see `doc_batching`. 3D batching ~~~~~~~~~~~ @@ -73,13 +73,13 @@ joining static objects often outweigh other considerations, especially for large numbers of distant or low-poly objects. For more information on 3D specific optimizations, see -:ref:`doc_optimizing_3d_performance`. +`doc_optimizing_3d_performance`. Reuse Shaders and Materials ~~~~~~~~~~~~~~~~~~~~~~~~~~~ The Godot renderer is a little different to what is out there. It's designed to -minimize GPU state changes as much as possible. :ref:`SpatialMaterial +minimize GPU state changes as much as possible. `SpatialMaterial ` does a good job at reusing materials that need similar shaders. If custom shaders are used, make sure to reuse them as much as possible. Godot's priorities are: @@ -175,7 +175,7 @@ elsewhere. You can increase performance in a fill rate-limited project by reducing the amount of work the GPU has to do. You can do this by simplifying the shader -(perhaps turn off expensive options if you are using a :ref:`SpatialMaterial +(perhaps turn off expensive options if you are using a `SpatialMaterial `), or reducing the number and size of textures used. **When targeting mobile devices, consider using the simplest possible shaders diff --git a/tutorials/performance/index.rst b/tutorials/performance/index.rst index 7f26247..157fae0 100644 --- a/tutorials/performance/index.rst +++ b/tutorials/performance/index.rst @@ -37,7 +37,7 @@ flexibility over performance. With this clear, the aim of this tutorial section is to explain how to get the maximum performance out of Godot. While the tutorials can be read in any order, -it is a good idea to start from :ref:`doc_general_optimization`. +it is a good idea to start from `doc_general_optimization`. Common ------ diff --git a/tutorials/performance/optimizing_3d_performance.rst b/tutorials/performance/optimizing_3d_performance.rst index 93ad389..9a722d4 100644 --- a/tutorials/performance/optimizing_3d_performance.rst +++ b/tutorials/performance/optimizing_3d_performance.rst @@ -49,7 +49,7 @@ Portal Rendering However, there is a much easier way to take advantage of occlusion. Godot features an advanced portal rendering system, which can perform occlusion culling from cameras and -lights. See :ref:`doc_rooms_and_portals`. +lights. See `doc_rooms_and_portals`. This is not a fully automatic system and it requires some manual setup. However, it potentially offers significant performance increases. @@ -71,7 +71,7 @@ through add-ons or may be available in core Godot in the future. Transparent objects ~~~~~~~~~~~~~~~~~~~ -Godot sorts objects by :ref:`Material ` and :ref:`Shader +Godot sorts objects by `Material ` and `Shader ` to improve performance. This, however, can not be done with transparent objects. Transparent objects are rendered from back to front to make blending with what is behind work. As a result, @@ -79,7 +79,7 @@ blending with what is behind work. As a result, small section with transparency, try to make that section a separate surface with its own material. -For more information, see the :ref:`GPU optimizations ` +For more information, see the `GPU optimizations ` doc. Level of detail (LOD) @@ -99,7 +99,7 @@ The simplest version of using transparency to deal with LOD is billboards. For example, you can use a single transparent quad to represent a tree at distance. This can be very cheap to render, unless of course, there are many trees in front of each other. In which case transparency may start eating into fill rate -(for more information on fill rate, see :ref:`doc_gpu_optimization`). +(for more information on fill rate, see `doc_gpu_optimization`). An alternative is to render not just one tree, but a number of trees together as a group. This can be especially effective if you can see an area but cannot @@ -116,12 +116,12 @@ Use instancing (MultiMesh) ~~~~~~~~~~~~~~~~~~~~~~~~~~ If several identical objects have to be drawn in the same place or nearby, try -using :ref:`MultiMesh ` instead. MultiMesh allows the drawing +using `MultiMesh ` instead. MultiMesh allows the drawing of many thousands of objects at very little performance cost, making it ideal for flocks, grass, particles, and anything else where you have thousands of identical objects. -Also see the :ref:`Using MultiMesh ` doc. +Also see the `Using MultiMesh ` doc. Bake lighting ============= @@ -135,7 +135,7 @@ but has the downside that it will not be dynamic. Sometimes, this is a trade-off worth making. In general, if several lights need to affect a scene, it's best to use -:ref:`doc_baked_lightmaps`. Baking can also improve the scene quality by adding +`doc_baked_lightmaps`. Baking can also improve the scene quality by adding indirect light bounces. Animation and skinning diff --git a/tutorials/performance/threads/thread_safe_apis.rst b/tutorials/performance/threads/thread_safe_apis.rst index ecec634..766ab3b 100644 --- a/tutorials/performance/threads/thread_safe_apis.rst +++ b/tutorials/performance/threads/thread_safe_apis.rst @@ -14,7 +14,7 @@ Below is a list of ways multithreading can be used in different areas of Godot. Global scope ------------ -:ref:`Global Scope` singletons are all thread-safe. Accessing servers from threads is supported (for VisualServer and Physics servers, ensure threaded or thread-safe operation is enabled in the project settings!). +`Global Scope` singletons are all thread-safe. Accessing servers from threads is supported (for VisualServer and Physics servers, ensure threaded or thread-safe operation is enabled in the project settings!). This makes them ideal for code that creates dozens of thousands of instances in servers and controls them from threads. Of course, it requires a bit more code, as this is used directly and not within the scene tree. diff --git a/tutorials/performance/threads/using_multiple_threads.rst b/tutorials/performance/threads/using_multiple_threads.rst index 5d6ab52..4883c2e 100644 --- a/tutorials/performance/threads/using_multiple_threads.rst +++ b/tutorials/performance/threads/using_multiple_threads.rst @@ -16,7 +16,7 @@ Godot supports threads and provides many handy functions to use them. .. warning:: - Before using a built-in class in a thread, read :ref:`doc_thread_safe_apis` + Before using a built-in class in a thread, read `doc_thread_safe_apis` first to check whether it can be safely used in a thread. Creating a Thread @@ -51,7 +51,7 @@ gdscript GDScript Your function will, then, run in a separate thread until it returns. Even if the function has returned already, the thread must collect it, so call -:ref:`Thread.wait_to_finish()`, which will +`Thread.wait_to_finish()`, which will wait until the thread is done (if not done yet), then properly dispose of it. Mutexes @@ -59,19 +59,19 @@ Mutexes Accessing objects or data from multiple threads is not always supported (if you do it, it will cause unexpected behaviors or crashes). Read the -:ref:`doc_thread_safe_apis` documentation to understand which engine APIs +`doc_thread_safe_apis` documentation to understand which engine APIs support multiple thread access. When processing your own data or calling your own functions, as a rule, try to avoid accessing the same data directly from different threads. You may run into synchronization problems, as the data is not always updated between CPU cores -when modified. Always use a :ref:`Mutex` when accessing +when modified. Always use a `Mutex` when accessing a piece of data from different threads. -When calling :ref:`Mutex.lock()`, a thread ensures that +When calling `Mutex.lock()`, a thread ensures that all other threads will be blocked (put on suspended state) if they try to *lock* the same mutex. When the mutex is unlocked by calling -:ref:`Mutex.unlock()`, the other threads will be +`Mutex.unlock()`, the other threads will be allowed to proceed with the lock (but only one at a time). Here is an example of using a Mutex: @@ -114,12 +114,12 @@ Semaphores Sometimes you want your thread to work *"on demand"*. In other words, tell it when to work and let it suspend when it isn't doing anything. -For this, :ref:`Semaphores` are used. The function -:ref:`Semaphore.wait()` is used in the thread to +For this, `Semaphores` are used. The function +`Semaphore.wait()` is used in the thread to suspend it until some data arrives. The main thread, instead, uses -:ref:`Semaphore.post()` to signal that data is +`Semaphore.post()` to signal that data is ready to be processed: gdscript GDScript diff --git a/tutorials/performance/using_multimesh.rst b/tutorials/performance/using_multimesh.rst index 201d350..3d27fa8 100644 --- a/tutorials/performance/using_multimesh.rst +++ b/tutorials/performance/using_multimesh.rst @@ -5,7 +5,7 @@ Optimization using MultiMeshes For large amount of instances (in the thousands), that need to be constantly processed (and certain amount of control needs to be retained), -:ref:`using servers directly ` is the recommended optimization. +`using servers directly ` is the recommended optimization. When the amount of objects reach the hundreds of thousands or millions, none of these approaches are efficient anymore. Still, depending on the requirements, there @@ -14,7 +14,7 @@ is one more optimization possible. MultiMeshes ----------- -A :ref:`MultiMesh` is a single draw primitive that can draw up to millions +A `MultiMesh` is a single draw primitive that can draw up to millions of objects in one go. It's extremely efficient because it uses the GPU hardware to do this (in OpenGL ES 2.0, it's less efficient because there is no hardware support for it, though). @@ -29,18 +29,18 @@ for different areas of the world. It is also possible to execute some logic inside the vertex shader (using the ``INSTANCE_ID`` or ``INSTANCE_CUSTOM`` built-in constants). For an example of animating thousands of objects in a MultiMesh, -see the :ref:`Animating thousands of fish ` tutorial. Information -to the shader can be provided via textures (there are floating-point :ref:`Image` formats +see the `Animating thousands of fish ` tutorial. Information +to the shader can be provided via textures (there are floating-point `Image` formats which are ideal for this). Another alternative is to use GDNative and C++, which should be extremely efficient (it's possible to set the entire state for all objects using linear memory via the -:ref:`VisualServer.multimesh_set_as_bulk_array() ` +`VisualServer.multimesh_set_as_bulk_array() ` function). This way, the array can be created with multiple threads, then set in one call, providing high cache efficiency. Finally, it's not required to have all MultiMesh instances visible. The amount of visible ones can be -controlled with the :ref:`MultiMesh.visible_instance_count ` +controlled with the `MultiMesh.visible_instance_count ` property. The typical workflow is to allocate the maximum amount of instances that will be used, then change the amount visible depending on how many are currently needed. diff --git a/tutorials/performance/using_servers.rst b/tutorials/performance/using_servers.rst index b5780f4..0b6c36a 100644 --- a/tutorials/performance/using_servers.rst +++ b/tutorials/performance/using_servers.rst @@ -4,7 +4,7 @@ Optimization using Servers ========================== Engines like Godot provide increased ease of use thanks to their high level constructs and features. -Most of them are accessed and used via the :ref:`Scene System`. Using nodes and +Most of them are accessed and used via the `Scene System`. Using nodes and resources simplifies project organization and asset management in complex games. There are, of course, always drawbacks: @@ -33,10 +33,10 @@ At the core, Godot uses the concept of Servers. They are very low-level APIs to rendering, physics, sound, etc. The scene system is built on top of them and uses them directly. The most common servers are: -* :ref:`VisualServer `: handles everything related to graphics. -* :ref:`PhysicsServer `: handles everything related to 3D physics. -* :ref:`Physics2DServer `: handles everything related to 2D physics. -* :ref:`AudioServer `: handles everything related to audio. +* `VisualServer `: handles everything related to graphics. +* `PhysicsServer `: handles everything related to 3D physics. +* `Physics2DServer `: handles everything related to 2D physics. +* `AudioServer `: handles everything related to audio. Explore their APIs and you will realize that all the functions provided are low-level implementations of everything Godot allows you to do. @@ -44,38 +44,38 @@ implementations of everything Godot allows you to do. RIDs ---- -The key to using servers is understanding Resource ID (:ref:`RID `) objects. These are opaque +The key to using servers is understanding Resource ID (`RID `) objects. These are opaque handles to the server implementation. They are allocated and freed manually. Almost every function in the servers requires RIDs to access the actual resource. Most Godot nodes and resources contain these RIDs from the servers internally, and they can -be obtained with different functions. In fact, anything that inherits :ref:`Resource ` +be obtained with different functions. In fact, anything that inherits `Resource ` can be directly casted to an RID. Not all resources contain an RID, though: in such cases, the RID will be empty. The resource can then be passed to server APIs as an RID. -.. Warning:: Resources are reference-counted (see :ref:`Reference `), and +.. Warning:: Resources are reference-counted (see `Reference `), and references to a resource's RID are *not* counted when determining whether the resource is still in use. Make sure to keep a reference to the resource outside the server, or else both it and its RID will be erased. For nodes, there are many functions available: -* For CanvasItem, the :ref:`CanvasItem.get_canvas_item() ` +* For CanvasItem, the `CanvasItem.get_canvas_item() ` method will return the canvas item RID in the server. -* For CanvasLayer, the :ref:`CanvasLayer.get_canvas() ` +* For CanvasLayer, the `CanvasLayer.get_canvas() ` method will return the canvas RID in the server. -* For Viewport, the :ref:`Viewport.get_viewport_rid() ` +* For Viewport, the `Viewport.get_viewport_rid() ` method will return the viewport RID in the server. -* For 3D, the :ref:`World ` resource (obtainable in the :ref:`Viewport ` - and :ref:`Spatial ` nodes) +* For 3D, the `World ` resource (obtainable in the `Viewport ` + and `Spatial ` nodes) contains functions to get the *VisualServer Scenario*, and the *PhysicsServer Space*. This allows creating 3D objects directly with the server API and using them. -* For 2D, the :ref:`World2D ` resource (obtainable in the :ref:`Viewport ` - and :ref:`CanvasItem ` nodes) +* For 2D, the `World2D ` resource (obtainable in the `Viewport ` + and `CanvasItem ` nodes) contains functions to get the *VisualServer Canvas*, and the *Physics2DServer Space*. This allows creating 2D objects directly with the server API and using them. -* The :ref:`VisualInstance` class, allows getting the scenario *instance* and - *instance base* via the :ref:`VisualInstance.get_instance() ` - and :ref:`VisualInstance.get_base() ` respectively. +* The `VisualInstance` class, allows getting the scenario *instance* and + *instance base* via the `VisualInstance.get_instance() ` + and `VisualInstance.get_base() ` respectively. Try exploring the nodes and resources you are familiar with and find the functions to obtain the server *RIDs*. @@ -86,7 +86,7 @@ Creating a sprite ----------------- This is a simple example of how to create a sprite from code and move it using the low-level -:ref:`CanvasItem ` API. +`CanvasItem ` API. gdscript GDScript @@ -160,8 +160,8 @@ gdscript GDScript Creating a 2D RigidBody and moving a sprite with it --------------------------------------------------- -This creates a :ref:`RigidBody2D ` using the :ref:`Physics2DServer ` API, -and moves a :ref:`CanvasItem ` when the body moves. +This creates a `RigidBody2D ` using the `Physics2DServer ` API, +and moves a `CanvasItem ` when the body moves. gdscript GDScript @@ -197,7 +197,7 @@ gdscript GDScript ``` The 3D version should be very similar, as 2D and 3D physics servers are identical (using -:ref:`RigidBody ` and :ref:`PhysicsServer ` respectively). +`RigidBody ` and `PhysicsServer ` respectively). Getting data from the servers ----------------------------- diff --git a/tutorials/performance/vertex_animation/animating_thousands_of_fish.rst b/tutorials/performance/vertex_animation/animating_thousands_of_fish.rst index f0d4c3a..88886f0 100644 --- a/tutorials/performance/vertex_animation/animating_thousands_of_fish.rst +++ b/tutorials/performance/vertex_animation/animating_thousands_of_fish.rst @@ -7,8 +7,8 @@ This tutorial explores a technique used in the game `ABZU ` and -a :ref:`MultiMeshInstance `. Using the following technique you +In Godot, this can be accomplished with a custom `Shader ` and +a `MultiMeshInstance `. Using the following technique you can render thousands of animated objects, even on low end hardware. We will start by animating one fish. Then, we will see how to extend that animation to @@ -17,8 +17,8 @@ thousands of fish. Animating one Fish ------------------ -We will start with a single fish. Load your fish model into a :ref:`MeshInstance ` -and add a new :ref:`ShaderMaterial `. +We will start with a single fish. Load your fish model into a `MeshInstance ` +and add a new `ShaderMaterial `. Here is the fish we will be using for the example images, you can use any fish model you like. @@ -28,7 +28,7 @@ Here is the fish we will be using for the example images, you can use any fish m shared with a creative commons license. CC0 1.0 Universal (CC0 1.0) Public Domain Dedication https://creativecommons.org/publicdomain/zero/1.0/ -Typically, you would use bones and a :ref:`Skeleton ` to animate objects. However, +Typically, you would use bones and a `Skeleton ` to animate objects. However, bones are animated on the CPU and so you end having to calculate thousands of operations every frame and it becomes impossible to have thousands of objects. Using vertex animation in a vertex shader, you avoid using bones and can instead calculate the full animation in a few lines of code @@ -187,12 +187,12 @@ A MultiMeshInstance node is created and used the same way you would make a MeshI For this tutorial, we will name the MultiMeshInstance node ``School``, because it will contain a school of fish. -Once you have a MultiMeshInstance add a :ref:`MultiMesh `, and to that -MultiMesh add your :ref:`Mesh ` with the shader from above. +Once you have a MultiMeshInstance add a `MultiMesh `, and to that +MultiMesh add your `Mesh ` with the shader from above. MultiMeshes draw your Mesh with three additional per-instance properties: Transform (rotation, translation, scale), Color, and Custom. Custom is used to pass in 4 multi-use variables using -a :ref:`Color `. +a `Color `. ``instance_count`` specifies how many instances of the mesh you want to draw. For now, leave ``instance_count`` at ``0`` because you cannot change any of the other parameters while @@ -212,7 +212,7 @@ Now, set ``instance_count`` to the number of fish you want to have. Next we need to set the per-instance transforms. There are two ways to set per-instance transforms for MultiMeshes. The first is entirely in editor -and is described in the :ref:`MultiMeshInstance tutorial `. +and is described in the `MultiMeshInstance tutorial `. The second is to loop over all the instances and set their transforms in code. Below, we use GDScript to loop over all the instances and set their transform to a random position. @@ -271,5 +271,5 @@ moving. You can move them by updating the per-instance transform for each fish e doing so will be faster than moving thousands of MeshInstances per frame, it'll still likely be slow. -In the next tutorial we will cover how to use :ref:`Particles ` to take advantage +In the next tutorial we will cover how to use `Particles ` to take advantage of the GPU and move each fish around individually while still receiving the benefits of instancing. diff --git a/tutorials/performance/vertex_animation/controlling_thousands_of_fish.rst b/tutorials/performance/vertex_animation/controlling_thousands_of_fish.rst index 44de676..f532046 100644 --- a/tutorials/performance/vertex_animation/controlling_thousands_of_fish.rst +++ b/tutorials/performance/vertex_animation/controlling_thousands_of_fish.rst @@ -3,20 +3,20 @@ Controlling thousands of fish with Particles ============================================ -The problem with :ref:`MeshInstances ` is that it is expensive to +The problem with `MeshInstances ` is that it is expensive to update their transform array. It is great for placing many static objects around the scene. But it is still difficult to move the objects around the scene. To make each instance move in an interesting way, we will use a -:ref:`Particles ` node. Particles take advantage of GPU acceleration -by computing and setting the per-instance information in a :ref:`Shader `. +`Particles ` node. Particles take advantage of GPU acceleration +by computing and setting the per-instance information in a `Shader `. -.. note:: Particles are not available in GLES2, instead use :ref:`CPUParticles `, +.. note:: Particles are not available in GLES2, instead use `CPUParticles `, which do the same thing as Particles, but do not benefit from GPU acceleration. First create a Particles node. Then, under "Draw Passes" set the Particle's "Draw Pass 1" to your -:ref:`Mesh `. Then under "Process Material" create a new -:ref:`ShaderMaterial `. +`Mesh `. Then under "Process Material" create a new +`ShaderMaterial `. Set the ``shader_type`` to ``particles``. @@ -48,7 +48,7 @@ Then add the following two functions: return x; } -These functions come from the default :ref:`ParticlesMaterial `. +These functions come from the default `ParticlesMaterial `. They are used to generate a random number from each particle's ``RANDOM_SEED``. A unique thing about particle shaders is that some built-in variables are saved across frames. @@ -140,5 +140,5 @@ This code gives you the following behavior: Using a ParticlesMaterial you can make the fish behavior as simple or complex as you like. In this tutorial we only set Velocity, but in your own Shaders you can also set ``COLOR``, rotation, scale -(through ``TRANSFORM``). Please refer to the :ref:`Particles Shader Reference ` +(through ``TRANSFORM``). Please refer to the `Particles Shader Reference ` for more information on particle shaders. diff --git a/tutorials/physics/collision_shapes_3d.rst b/tutorials/physics/collision_shapes_3d.rst index 0b43b31..c505e69 100644 --- a/tutorials/physics/collision_shapes_3d.rst +++ b/tutorials/physics/collision_shapes_3d.rst @@ -12,9 +12,9 @@ This guide explains: Godot provides many kinds of collision shapes, with different performance and accuracy tradeoffs. -You can define the shape of a :ref:`class_PhysicsBody` by adding one or more -:ref:`CollisionShapes ` as child nodes. Note that you must -add a :ref:`class_Shape` *resource* to collision shape nodes in the Inspector +You can define the shape of a `class_PhysicsBody` by adding one or more +`CollisionShapes ` as child nodes. Note that you must +add a `class_Shape` *resource* to collision shape nodes in the Inspector dock. .. note:: @@ -27,10 +27,10 @@ Primitive collision shapes Godot provides the following primitive collision shape types: -- :ref:`class_BoxShape` -- :ref:`class_SphereShape` -- :ref:`class_CapsuleShape` -- :ref:`class_CylinderShape` +- `class_BoxShape` +- `class_SphereShape` +- `class_CapsuleShape` +- `class_CylinderShape` You can represent the collision of most smaller objects using one or more primitive shapes. However, for more complex objects, such as a large ship or a @@ -43,7 +43,7 @@ better performance as well. Convex collision shapes ----------------------- -:ref:`Convex collision shapes ` are a compromise +`Convex collision shapes ` are a compromise between primitive collision shapes and concave collision shapes. They can represent shapes of any complexity, but with an important caveat. As their name implies, an individual shape can only represent a *convex* shape. For instance, @@ -75,7 +75,7 @@ viewport. The editor exposes two generation modes: Concave or trimesh collision shapes ----------------------------------- -:ref:`Concave collision shapes `, also called trimesh +`Concave collision shapes `, also called trimesh collision shapes, can take any form, from a few triangles to thousands of triangles. Concave shapes are the slowest option but are also the most accurate in Godot. **You can only use concave shapes within StaticBodies.** They will not @@ -121,7 +121,7 @@ editor exposes two options: .. seealso:: Godot can generate collision shapes for your imported 3D scenes - automatically. See :ref:`doc_importing_scenes_import_hints` in the + automatically. See `doc_importing_scenes_import_hints` in the documentation for more information. Performance caveats diff --git a/tutorials/physics/interpolation/advanced_physics_interpolation.rst b/tutorials/physics/interpolation/advanced_physics_interpolation.rst index b4a7287..eee6280 100644 --- a/tutorials/physics/interpolation/advanced_physics_interpolation.rst +++ b/tutorials/physics/interpolation/advanced_physics_interpolation.rst @@ -8,16 +8,16 @@ Although the previous instructions will give satisfactory results in a lot of ga Exceptions to automatic physics interpolation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Even with physics interpolation active, there may be some local situations where you would benefit from disabling automatic interpolation for a :ref:`Node` (or branch of the :ref:`SceneTree`), and have the finer control of performing interpolation manually. +Even with physics interpolation active, there may be some local situations where you would benefit from disabling automatic interpolation for a `Node` (or branch of the `SceneTree`), and have the finer control of performing interpolation manually. -This is possible using the :ref:`Node.physics_interpolation_mode` property which is present in all Nodes. If you for example, turn off interpolation for a Node, the children will recursively also be affected (as they default to inheriting the parent setting). This means you can easily disable interpolation for an entire subscene. +This is possible using the `Node.physics_interpolation_mode` property which is present in all Nodes. If you for example, turn off interpolation for a Node, the children will recursively also be affected (as they default to inheriting the parent setting). This means you can easily disable interpolation for an entire subscene. The most common situation where you may want to perform your own interpolation is Cameras. Cameras ^^^^^^^ -In many cases, a :ref:`Camera` can use automatic interpolation just like any other node. However, for best results, especially at low physics tick rates, it is recommended that you take a manual approach to Camera interpolation. +In many cases, a `Camera` can use automatic interpolation just like any other node. However, for best results, especially at low physics tick rates, it is recommended that you take a manual approach to Camera interpolation. This is because viewers are very sensitive to Camera movement. For instance, a Camera that realigns slightly every 1/10th of a second (at 10tps tick rate) will often be noticeable. You can get a much smoother result by moving the Camera each frame in ``_process``, and following an interpolated target manually. @@ -34,7 +34,7 @@ There are two ways of doing this: .. image:: img/fti_camera_worldspace.png -2) Call :ref:`Spatial.set_as_toplevel` and set this to ``true``, which will make the Camera ignore the transform of its parent. +2) Call `Spatial.set_as_toplevel` and set this to ``true``, which will make the Camera ignore the transform of its parent. Typical example ^^^^^^^^^^^^^^^ @@ -48,7 +48,7 @@ get_global_transform_interpolated() What we really want to focus the Camera on, is not the position of the target on the physics tick, but the *interpolated* position, i.e. the position at which the target will be rendered. -We can do this using the :ref:`Spatial.get_global_transform_interpolated` function. This acts exactly like getting :ref:`Spatial.global_transform` but it gives you the *interpolated* transform (during a ``_process()`` call). +We can do this using the `Spatial.get_global_transform_interpolated` function. This acts exactly like getting `Spatial.global_transform` but it gives you the *interpolated* transform (during a ``_process()`` call). .. important:: ``get_global_transform_interpolated()`` should only be used once or twice for special cases such as Cameras. It should **not** be used all over the place in your code (both for performance reasons, and to give correct gameplay). @@ -93,12 +93,12 @@ Mouse look Mouse look is a very common way of controlling Cameras. But there is a problem. Unlike keyboard input which can be sampled periodically on the physics tick, mouse move events can come in continuously. The Camera will be expected to react and follow these mouse movements on the next frame, rather than waiting until the next physics tick. -In this situation, it can be better to disable physics interpolation for the Camera node (using :ref:`Node.physics_interpolation_mode`) and directly apply the mouse input to the Camera rotation, rather than apply it in ``_physics_process``. +In this situation, it can be better to disable physics interpolation for the Camera node (using `Node.physics_interpolation_mode`) and directly apply the mouse input to the Camera rotation, rather than apply it in ``_physics_process``. Sometimes, especially with Cameras, you will want to use a combination of interpolation and non-interpolation: -* A first person camera may position the camera at a player location (perhaps using :ref:`Spatial.get_global_transform_interpolated`), but control the Camera rotation from mouse look *without* interpolation. -* A third person camera may similarly determine the look at (target location) of the camera using :ref:`Spatial.get_global_transform_interpolated`, but position the camera using mouse look *without* interpolation. +* A first person camera may position the camera at a player location (perhaps using `Spatial.get_global_transform_interpolated`), but control the Camera rotation from mouse look *without* interpolation. +* A third person camera may similarly determine the look at (target location) of the camera using `Spatial.get_global_transform_interpolated`, but position the camera using mouse look *without* interpolation. There are many permutations and variations of Camera types, but it should be clear that in many cases, disabling automatic physics interpolation and handling this yourself can give a better result. @@ -113,7 +113,7 @@ MultiMeshes Although most visual Nodes follow the single Node single visual instance paradigm, MultiMeshes can control several instances from the same Node. Therefore, they have some extra functions for controlling interpolation functionality on a *per-instance* basis. You should explore these functions if you are using interpolated MultiMeshes. -- :ref:`MultiMesh.reset_instance_physics_interpolation` -- :ref:`MultiMesh.set_as_bulk_array_interpolated` +- `MultiMesh.reset_instance_physics_interpolation` +- `MultiMesh.set_as_bulk_array_interpolated` -Full details are in the :ref:`MultiMesh` documentation. +Full details are in the `MultiMesh` documentation. diff --git a/tutorials/physics/interpolation/physics_interpolation_introduction.rst b/tutorials/physics/interpolation/physics_interpolation_introduction.rst index aef083a..81d476e 100644 --- a/tutorials/physics/interpolation/physics_interpolation_introduction.rst +++ b/tutorials/physics/interpolation/physics_interpolation_introduction.rst @@ -6,7 +6,7 @@ Introduction Physics ticks and rendered frames ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -One key concept to understand in Godot is the distinction between physics ticks (sometimes referred to as iterations or physics frames), and rendered frames. The physics proceeds at a fixed tick rate (set in :ref:`ProjectSettings.physics/common/physics_fps`), which defaults to 60 ticks per second. +One key concept to understand in Godot is the distinction between physics ticks (sometimes referred to as iterations or physics frames), and rendered frames. The physics proceeds at a fixed tick rate (set in `ProjectSettings.physics/common/physics_fps`), which defaults to 60 ticks per second. However, the engine does not necessarily **render** at the same rate. Although many monitors refresh at 60 Hz (cycles per second), many refresh at completely different frequencies (e.g. 75 Hz, 144 Hz, 240 Hz or more). Even though a monitor may be able to show a new frame e.g. 60 times a second, there is no guarantee that the CPU and GPU will be able to *supply* frames at this rate. For instance, when running with V-Sync, the computer may be too slow for 60 and only reach the deadlines for 30 FPS, in which case the frames you see will change at 30 FPS (resulting in stuttering). @@ -73,7 +73,7 @@ First of all, we have to calculate how far through the physics tick we want the fraction = 0.02 / 0.10 fraction = 0.2 -This is called the **physics interpolation fraction**, and is handily calculated for you by Godot. It can be retrieved on any frame by calling :ref:`Engine.get_physics_interpolation_fraction`. +This is called the **physics interpolation fraction**, and is handily calculated for you by Godot. It can be retrieved on any frame by calling `Engine.get_physics_interpolation_fraction`. Calculating the interpolated position ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/tutorials/physics/interpolation/physics_interpolation_quick_start_guide.rst b/tutorials/physics/interpolation/physics_interpolation_quick_start_guide.rst index fb279c4..201a4ac 100644 --- a/tutorials/physics/interpolation/physics_interpolation_quick_start_guide.rst +++ b/tutorials/physics/interpolation/physics_interpolation_quick_start_guide.rst @@ -3,7 +3,7 @@ Quick start guide ================= -- Turn on physics interpolation: :ref:`ProjectSettings.physics/common/physics_interpolation` +- Turn on physics interpolation: `ProjectSettings.physics/common/physics_interpolation` - Make sure you move objects and run your game logic in ``_physics_process()`` rather than ``_process()``. This includes moving objects directly *and indirectly* (by e.g. moving a parent, or using another mechanism to automatically move nodes). -- Be sure to call :ref:`Node.reset_physics_interpolation` on nodes *after* you first position or teleport them, to prevent "streaking" -- Temporarily try setting :ref:`ProjectSettings.physics/common/physics_fps` to 10 to see the difference with and without interpolation. +- Be sure to call `Node.reset_physics_interpolation` on nodes *after* you first position or teleport them, to prevent "streaking" +- Temporarily try setting `ProjectSettings.physics/common/physics_fps` to 10 to see the difference with and without interpolation. diff --git a/tutorials/physics/interpolation/using_physics_interpolation.rst b/tutorials/physics/interpolation/using_physics_interpolation.rst index 2ef51f2..f5acd5f 100644 --- a/tutorials/physics/interpolation/using_physics_interpolation.rst +++ b/tutorials/physics/interpolation/using_physics_interpolation.rst @@ -9,13 +9,13 @@ We have tried to make the system as easy to use as possible, and many existing g Turn on the physics interpolation setting ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The first step is to turn on physics interpolation in :ref:`ProjectSettings.physics/common/physics_interpolation`. You can now run your game. +The first step is to turn on physics interpolation in `ProjectSettings.physics/common/physics_interpolation`. You can now run your game. It is likely that nothing looks hugely different, particularly if you are running physics at 60 TPS or a multiple of it. However, quite a bit more is happening behind the scenes. .. tip:: - To convert an existing game to use interpolation, it is highly recommended that you temporarily set :ref:`ProjectSettings.physics/common/physics_fps` to a low value such as 10, which will make interpolation problems more obvious. + To convert an existing game to use interpolation, it is highly recommended that you temporarily set `ProjectSettings.physics/common/physics_fps` to a low value such as 10, which will make interpolation problems more obvious. Move (almost) all game logic from _process to _physics_process ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -34,7 +34,7 @@ Ensure that all indirect movement happens during physics ticks Consider that in Godot, Nodes can be moved not just directly in your own scripts, but also by automatic methods such as tweening, animation, and navigation. All these methods should also have their timing set to operate on the physics tick rather than each frame ("idle"), **if** you are using them to move objects (*these methods can also be used to control properties that are not interpolated*). -.. note:: Also consider that nodes can be moved not just by moving themselves, but also by moving parent nodes in the :ref:`SceneTree`. The movement of parents should therefore also only occur during physics ticks. +.. note:: Also consider that nodes can be moved not just by moving themselves, but also by moving parent nodes in the `SceneTree`. The movement of parents should therefore also only occur during physics ticks. Choose a physics tick rate ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -58,7 +58,7 @@ Call reset_physics_interpolation() when teleporting objects Most of the time, interpolation is what you want between two physics ticks. However, there is one situation in which it may *not* be what you want. That is when you are initially placing objects, or moving them to a new location. Here, you don't want a smooth motion between the two - you want an instantaneous move. -The solution to this is to call the :ref:`Node.reset_physics_interpolation` function. You should call this function on a Node *after* setting the position/transform. The rest is done for you automatically. +The solution to this is to call the `Node.reset_physics_interpolation` function. You should call this function on a Node *after* setting the position/transform. The rest is done for you automatically. Even if you forget to call this, it is not usually a problem in most situations (especially at high tick rates). This is something you can easily leave to the polishing phase of your game. The worst that will happen is seeing a streaking motion for a frame or so when you move them - you will know when you need it! @@ -69,6 +69,6 @@ Testing and debugging tips Even if you intend to run physics at 60 TPS, in order to thoroughly test your interpolation and get the smoothest gameplay, it is highly recommended to temporarily set the physics tick rate to a low value such as 10 TPS. -The gameplay may not work perfectly, but it should enable you to more easily see cases where you should be calling :ref:`Node.reset_physics_interpolation`, or where you should be using your own custom interpolation on e.g. a :ref:`Camera`. Once you have these cases fixed, you can set the physics tick rate back to the desired setting. +The gameplay may not work perfectly, but it should enable you to more easily see cases where you should be calling `Node.reset_physics_interpolation`, or where you should be using your own custom interpolation on e.g. a `Camera`. Once you have these cases fixed, you can set the physics tick rate back to the desired setting. The other great advantage to testing at a low tick rate is you can often notice other game systems that are synchronized to the physics tick and creating glitches which you may want to work around. Typical examples include setting animation blend values, which you may decide to set in ``_process()`` and interpolate manually. diff --git a/tutorials/physics/kinematic_character_2d.rst b/tutorials/physics/kinematic_character_2d.rst index d98cff2..a6a3354 100644 --- a/tutorials/physics/kinematic_character_2d.rst +++ b/tutorials/physics/kinematic_character_2d.rst @@ -101,8 +101,8 @@ Moving the kinematic character Go back to the character scene, and open the script, the magic begins now! Kinematic body will do nothing by default, but it has a useful function called -:ref:`KinematicBody2D.move_and_collide() `. -This function takes a :ref:`Vector2 ` as +`KinematicBody2D.move_and_collide() `. +This function takes a `Vector2 ` as an argument, and tries to apply that motion to the kinematic body. If a collision happens, it stops right at the moment of the collision. diff --git a/tutorials/physics/physics_introduction.rst b/tutorials/physics/physics_introduction.rst index 7a313c2..14303e0 100644 --- a/tutorials/physics/physics_introduction.rst +++ b/tutorials/physics/physics_introduction.rst @@ -26,50 +26,50 @@ In this guide, you will learn: Collision objects ----------------- -Godot offers four kinds of physics bodies, extending :ref:`CollisionObject2D `: +Godot offers four kinds of physics bodies, extending `CollisionObject2D `: -- :ref:`Area2D ` +- `Area2D ` ``Area2D`` nodes provide **detection** and **influence**. They can detect when objects overlap and can emit signals when bodies enter or exit. An ``Area2D`` can also be used to override physics properties, such as gravity or damping, in a defined area. -The other three bodies extend :ref:`PhysicsBody2D `: +The other three bodies extend `PhysicsBody2D `: -- :ref:`StaticBody2D ` +- `StaticBody2D ` A static body is one that is not moved by the physics engine. It participates in collision detection, but does not move in response to the collision. They are most often used for objects that are part of the environment or that do not need to have any dynamic behavior. -- :ref:`RigidBody2D ` +- `RigidBody2D ` This is the node that implements simulated 2D physics. You do not control a ``RigidBody2D`` directly, but instead you apply forces to it (gravity, impulses, - etc.) and the physics engine calculates the resulting movement. :ref:`Read more about using rigid bodies. ` + etc.) and the physics engine calculates the resulting movement. `Read more about using rigid bodies. ` -- :ref:`KinematicBody2D ` +- `KinematicBody2D ` A body that provides collision detection, but no physics. All movement and collision response must be implemented in code. Physics material ~~~~~~~~~~~~~~~~ -Static bodies and rigid bodies can be configured to use a :ref:`physics material +Static bodies and rigid bodies can be configured to use a `physics material `. This allows adjusting the friction and bounce of an object, and set if it's absorbent and/or rough. Collision shapes ~~~~~~~~~~~~~~~~ -A physics body can hold any number of :ref:`Shape2D ` objects +A physics body can hold any number of `Shape2D ` objects as children. These shapes are used to define the object's collision bounds and to detect contact with other objects. .. note:: In order to detect collisions, at least one ``Shape2D`` must be assigned to the object. -The most common way to assign a shape is by adding a :ref:`CollisionShape2D ` -or :ref:`CollisionPolygon2D ` as a child of the object. +The most common way to assign a shape is by adding a `CollisionShape2D ` +or `CollisionPolygon2D ` as a child of the object. These nodes allow you to draw the shape directly in the editor workspace. .. important:: Be careful to never scale your collision shapes in the editor. @@ -89,7 +89,7 @@ of a body's state variables such as ``position`` or ``linear velocity`` may not be accurate for the current frame. In order to avoid this inaccuracy, any code that needs to access a body's properties should -be run in the :ref:`Node._physics_process() ` +be run in the `Node._physics_process() ` callback, which is called before each physics step at a constant frame rate (60 times per second by default). This method will be passed a ``delta`` parameter, which is a floating-point number equal to the time passed in @@ -185,7 +185,7 @@ objects overlap and emit signals when bodies enter or exit. Areas can also be used to override physics properties, such as gravity or damping, in a defined area. -There are three main uses for :ref:`Area2D `: +There are three main uses for `Area2D `: - Overriding physics parameters (such as gravity) in a given region. @@ -216,7 +216,7 @@ RigidBody2D ----------- This is the node that implements simulated 2D physics. You do not control a -:ref:`RigidBody2D ` directly. Instead, you apply forces +`RigidBody2D ` directly. Instead, you apply forces to it and the physics engine calculates the resulting movement, including collisions with other bodies, and collision responses, such as bouncing, rotating, etc. @@ -225,7 +225,7 @@ You can modify a rigid body's behavior via properties such as "Mass", "Friction", or "Bounce", which can be set in the Inspector. The body's behavior is also affected by the world's properties, as set in -`Project Settings -> Physics`, or by entering an :ref:`Area2D ` +`Project Settings -> Physics`, or by entering an `Area2D ` that is overriding the global physics properties. When a rigid body is at rest and hasn't moved for a while, it goes to sleep. @@ -239,9 +239,9 @@ Rigid body modes A rigid body can be set to one of four modes: - **Rigid** - The body behaves as a physical object. It collides with other bodies and responds to forces applied to it. This is the default mode. -- **Static** - The body behaves like a :ref:`StaticBody2D ` and does not move. +- **Static** - The body behaves like a `StaticBody2D ` and does not move. - **Character** - Similar to "Rigid" mode, but the body cannot rotate. -- **Kinematic** - The body behaves like a :ref:`KinematicBody2D ` and must be moved by code. +- **Kinematic** - The body behaves like a `KinematicBody2D ` and must be moved by code. Using RigidBody2D ~~~~~~~~~~~~~~~~~ @@ -255,9 +255,9 @@ automatically be calculated by the physics engine. However, if you do wish to have some control over the body, you should take care - altering the ``position``, ``linear_velocity``, or other physics properties of a rigid body can result in unexpected behavior. If you need to alter any -of the physics-related properties, you should use the :ref:`_integrate_forces() ` +of the physics-related properties, you should use the `_integrate_forces() ` callback instead of ``_physics_process()``. In this callback, you have access -to the body's :ref:`Physics2DDirectBodyState `, +to the body's `Physics2DDirectBodyState `, which allows for safely changing properties and synchronizing them with the physics engine. @@ -291,7 +291,7 @@ the body and letting the physics engine calculate the resulting movement. .. note:: When a rigid body goes to sleep, the ``_integrate_forces()`` function will not be called. To override this behavior, you will need to keep the body awake by creating a collision, applying a - force to it, or by disabling the :ref:`can_sleep ` + force to it, or by disabling the `can_sleep ` property. Be aware that this can have a negative effect on performance. Contact reporting @@ -299,19 +299,19 @@ Contact reporting By default, rigid bodies do not keep track of contacts, because this can require a huge amount of memory if many bodies are in the scene. To enable -contact reporting, set the :ref:`contacts_reported ` +contact reporting, set the `contacts_reported ` property to a non-zero value. The contacts can then be obtained via -:ref:`Physics2DDirectBodyState.get_contact_count() ` +`Physics2DDirectBodyState.get_contact_count() ` and related functions. -Contact monitoring via signals can be enabled via the :ref:`contact_monitor ` -property. See :ref:`RigidBody2D ` for the list of available +Contact monitoring via signals can be enabled via the `contact_monitor ` +property. See `RigidBody2D ` for the list of available signals. KinematicBody2D --------------- -:ref:`KinematicBody2D ` bodies detect collisions with +`KinematicBody2D ` bodies detect collisions with other bodies, but are not affected by physics properties like gravity or friction. Instead, they must be controlled by the user via code. The physics engine will not move a kinematic body. @@ -329,11 +329,11 @@ After a collision, you may want the body to bounce, to slide along a wall, or to alter the properties of the object it hit. The way you handle collision response depends on which method you used to move the KinematicBody2D. -:ref:`move_and_collide ` +`move_and_collide ` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When using ``move_and_collide()``, the function returns a -:ref:`KinematicCollision2D ` object, which contains +`KinematicCollision2D ` object, which contains information about the collision and the colliding body. You can use this information to determine the response. @@ -368,7 +368,7 @@ gdscript GDScript velocity = velocity.bounce(collision_info.normal) ``` -:ref:`move_and_slide ` +`move_and_slide ` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Sliding is a common collision response; imagine a player moving along walls @@ -415,5 +415,5 @@ gdscript GDScript ``` -See :ref:`doc_kinematic_character_2d` for more details on using ``move_and_slide()``, +See `doc_kinematic_character_2d` for more details on using ``move_and_slide()``, including a demo project with detailed code. diff --git a/tutorials/physics/ragdoll_system.rst b/tutorials/physics/ragdoll_system.rst index ca73b7e..2e36e4f 100644 --- a/tutorials/physics/ragdoll_system.rst +++ b/tutorials/physics/ragdoll_system.rst @@ -18,7 +18,7 @@ Setting up the ragdoll Creating physical bones ~~~~~~~~~~~~~~~~~~~~~~~ -Like many other features in the engine, there is a node to set up a ragdoll: the :ref:`PhysicalBone ` node. To simplify the setup, you can generate ``PhysicalBone`` nodes with the "Create physical skeleton" feature in the skeleton node. +Like many other features in the engine, there is a node to set up a ragdoll: the `PhysicalBone ` node. To simplify the setup, you can generate ``PhysicalBone`` nodes with the "Create physical skeleton" feature in the skeleton node. Open the platformer demo in Godot, and then the Robi scene. Select the ``Skeleton`` node. A skeleton button appears on the top bar menu: @@ -82,4 +82,4 @@ Make sure to set up your collision layers and masks properly so the ``KinematicB .. image:: img/ragdoll_layer.png -For more information, read :ref:`doc_physics_introduction_collision_layers_and_masks`. +For more information, read `doc_physics_introduction_collision_layers_and_masks`. diff --git a/tutorials/physics/ray-casting.rst b/tutorials/physics/ray-casting.rst index c793ff0..39b2c75 100644 --- a/tutorials/physics/ray-casting.rst +++ b/tutorials/physics/ray-casting.rst @@ -14,7 +14,7 @@ do this in 2D and 3D. Godot stores all the low level game information in servers, while the scene is just a frontend. As such, ray casting is generally a lower-level task. For simple raycasts, node such as -:ref:`RayCast ` and :ref:`RayCast2D ` +`RayCast ` and `RayCast2D ` will work, as they will return every frame what the result of a raycast is. @@ -27,12 +27,12 @@ Space In the physics world, Godot stores all the low level collision and physics information in a *space*. The current 2d space (for 2D Physics) can be obtained by accessing -:ref:`CanvasItem.get_world_2d().space `. -For 3D, it's :ref:`Spatial.get_world().space `. +`CanvasItem.get_world_2d().space `. +For 3D, it's `Spatial.get_world().space `. -The resulting space :ref:`RID ` can be used in -:ref:`PhysicsServer ` and -:ref:`Physics2DServer ` respectively for 3D and 2D. +The resulting space `RID ` can be used in +`PhysicsServer ` and +`Physics2DServer ` respectively for 3D and 2D. Accessing space --------------- @@ -40,13 +40,13 @@ Accessing space Godot physics runs by default in the same thread as game logic, but may be set to run on a separate thread to work more efficiently. Due to this, the only time accessing space is safe is during the -:ref:`Node._physics_process() ` +`Node._physics_process() ` callback. Accessing it from outside this function may result in an error due to space being *locked*. To perform queries into physics space, the -:ref:`Physics2DDirectSpaceState ` -and :ref:`PhysicsDirectSpaceState ` +`Physics2DDirectSpaceState ` +and `PhysicsDirectSpaceState ` must be used. Use the following code in 2D: @@ -81,7 +81,7 @@ Raycast query ------------- For performing a 2D raycast query, the method -:ref:`Physics2DDirectSpaceState.intersect_ray() ` +`Physics2DDirectSpaceState.intersect_ray() ` may be used. For example: gdscript GDScript @@ -169,18 +169,18 @@ gdscript GDScript [self], collision_mask) ``` -See :ref:`doc_physics_introduction_collision_layer_code_example` for details on how to set the collision mask. +See `doc_physics_introduction_collision_layer_code_example` for details on how to set the collision mask. 3D ray casting from screen -------------------------- Casting a ray from screen to 3D physics space is useful for object picking. There is not much need to do this because -:ref:`CollisionObject ` +`CollisionObject ` has an "input_event" signal that will let you know when it was clicked, but in case there is any desire to do it manually, here's how. -To cast a ray from the screen, you need a :ref:`Camera ` +To cast a ray from the screen, you need a `Camera ` node. A ``Camera`` can be in two projection modes: perspective and orthogonal. Because of this, both the ray origin and direction must be obtained. This is because ``origin`` changes in orthogonal mode, while diff --git a/tutorials/physics/rigid_body.rst b/tutorials/physics/rigid_body.rst index f26a634..368a7ed 100644 --- a/tutorials/physics/rigid_body.rst +++ b/tutorials/physics/rigid_body.rst @@ -7,7 +7,7 @@ What is a rigid body? --------------------- A rigid body is one that is directly controlled by the physics engine in order to simulate the behavior of physical objects. -In order to define the shape of the body, it must have one or more :ref:`Shape ` objects assigned. Note that setting the position of these shapes will affect the body's center of mass. +In order to define the shape of the body, it must have one or more `Shape ` objects assigned. Note that setting the position of these shapes will affect the body's center of mass. How to control a rigid body --------------------------- @@ -15,12 +15,12 @@ How to control a rigid body A rigid body's behavior can be altered by setting its properties, such as mass and weight. A physics material needs to be added to the rigid body to adjust its friction and bounce, and set if it's absorbent and/or rough. These properties can be set in the Inspector or via code. -See :ref:`RigidBody ` and :ref:`PhysicsMaterial ` for +See `RigidBody ` and `PhysicsMaterial ` for the full list of properties and their effects. There are several ways to control a rigid body's movement, depending on your desired application. -If you only need to place a rigid body once, for example to set its initial location, you can use the methods provided by the :ref:`Spatial ` node, such as ``set_global_transform()`` or ``look_at()``. However, these methods cannot be called every frame or the physics engine will not be able to correctly simulate the body's state. +If you only need to place a rigid body once, for example to set its initial location, you can use the methods provided by the `Spatial ` node, such as ``set_global_transform()`` or ``look_at()``. However, these methods cannot be called every frame or the physics engine will not be able to correctly simulate the body's state. As an example, consider a rigid body that you want to rotate so that it points towards another object. A common mistake when implementing this kind of behavior is to use ``look_at()`` every frame, which breaks the physics simulation. Below, we'll demonstrate how to implement this correctly. The fact that you can't use ``set_global_transform()`` or ``look_at()`` methods doesn't mean that you can't have full control of a rigid body. Instead, you can control it by using the ``_integrate_forces()`` callback. In this method, you can add *forces*, apply *impulses*, or set the *velocity* in order to achieve any movement you desire. diff --git a/tutorials/physics/soft_body.rst b/tutorials/physics/soft_body.rst index 875265f..b7823ad 100644 --- a/tutorials/physics/soft_body.rst +++ b/tutorials/physics/soft_body.rst @@ -9,7 +9,7 @@ This can for example be used to simulate cloth or to create more realistic chara Basic set-up ~~~~~~~~~~~~ -A :ref:`SoftBody ` node is used for soft body simulations. +A `SoftBody ` node is used for soft body simulations. We will create a bouncy cube to demonstrate the setup of a soft body. @@ -42,7 +42,7 @@ Open the ``PlaneMesh`` properties and set the size(x: 0.5 y: 1) then set ``Subdi .. tip:: Subdivision generates a more tessellated mesh for better simulations. -Add a :ref:`BoneAttachment ` node under the skeleton node and select the Neck bone to attach the cloak to the character skeleton. +Add a `BoneAttachment ` node under the skeleton node and select the Neck bone to attach the cloak to the character skeleton. .. note:: ``BoneAttachment`` node is to attach objects to a bone of a armature. The attached object will follow the bone's movement, weapon of a character can be attached this way. diff --git a/tutorials/physics/using_area_2d.rst b/tutorials/physics/using_area_2d.rst index 6fac771..9273578 100644 --- a/tutorials/physics/using_area_2d.rst +++ b/tutorials/physics/using_area_2d.rst @@ -10,16 +10,16 @@ Godot offers a number of collision objects to provide both collision detection and response. Trying to decide which one to use for your project can be confusing. You can avoid problems and simplify development if you understand how each of them works and what their pros and cons are. In this tutorial, we'll look at the -:ref:`Area2D ` node and show some examples of how it can be used. +`Area2D ` node and show some examples of how it can be used. .. note:: This document assumes you're familiar with Godot's various physics - bodies. Please read :ref:`doc_physics_introduction` first. + bodies. Please read `doc_physics_introduction` first. What is an area? ---------------- An Area2D defines a region of 2D space. In this space you can detect other -:ref:`CollisionObject2D ` nodes overlapping, entering, +`CollisionObject2D ` nodes overlapping, entering, and exiting. Areas also allow for overriding local physics properties. We'll explore each of these functions below. @@ -41,7 +41,7 @@ and mask(s). The "Audio Bus" section allows you to override audio in the area, for example to apply an audio effect when the player moves through. -Note that Area2D extends :ref:`CollisionObject2D `, so it +Note that Area2D extends `CollisionObject2D `, so it also provides properties inherited from that class, such as ``input_pickable``. Overlap detection @@ -65,7 +65,7 @@ use ``area_entered``. However, let's assume our player is a ``KinematicBody2D`` (and therefore a ``CollisionObject2D`` type), so we'll connect the ``body_entered`` signal. -.. note:: If you're not familiar with using signals, see :ref:`doc_signals` for +.. note:: If you're not familiar with using signals, see `doc_signals` for an introduction. gdscript GDScript @@ -85,7 +85,7 @@ Some other usage examples: - Use a large circular area around an enemy to define its "detect" radius. When the player is outside the area, the enemy can't "see" it. - "Security cameras" - In a large level with multiple cameras, attach areas to each camera and activate them when the player enters. -See the :ref:`doc_your_first_2d_game` for an example of using Area2D in a game. +See the `doc_your_first_2d_game` for an example of using Area2D in a game. Area influence -------------- diff --git a/tutorials/physics/using_kinematic_body_2d.rst b/tutorials/physics/using_kinematic_body_2d.rst index e64f1cc..5aa8a56 100644 --- a/tutorials/physics/using_kinematic_body_2d.rst +++ b/tutorials/physics/using_kinematic_body_2d.rst @@ -10,11 +10,11 @@ Godot offers several collision objects to provide both collision detection and response. Trying to decide which one to use for your project can be confusing. You can avoid problems and simplify development if you understand how each of them works and what their pros and cons are. In this tutorial, we'll look at the -:ref:`KinematicBody2D ` node and show some examples +`KinematicBody2D ` node and show some examples of how to use it. .. note:: This document assumes you're familiar with Godot's various physics - bodies. Please read :ref:`doc_physics_introduction` first. + bodies. Please read `doc_physics_introduction` first. What is a kinematic body? ------------------------- @@ -46,11 +46,11 @@ see examples of how they work. ``move_and_collide`` ~~~~~~~~~~~~~~~~~~~~ -This method takes one parameter: a :ref:`Vector2 ` indicating the body's +This method takes one parameter: a `Vector2 ` indicating the body's relative movement. Typically, this is your velocity vector multiplied by the frame timestep (``delta``). If the engine detects a collision anywhere along this vector, the body will immediately stop moving. If this happens, the -method will return a :ref:`KinematicCollision2D ` object. +method will return a `KinematicCollision2D ` object. ``KinematicCollision2D`` is an object containing data about the collision and the colliding object. Using this data, you can calculate your collision @@ -92,7 +92,7 @@ other parameters allowing you to customize the slide behavior: - ``infinite_inertia`` - *default value:* ``true`` -When this parameter is ``true``, the body can push :ref:`RigidBody2D ` +When this parameter is ``true``, the body can push `RigidBody2D ` nodes, ignoring their mass, but won't detect collisions with them. If it's ``false`` the body will collide with rigid bodies and stop. @@ -133,7 +133,7 @@ gdscript GDScript .. note:: `get_slide_count()` only counts times the body has collided and changed direction. -See :ref:`KinematicCollision2D ` for details on what +See `KinematicCollision2D ` for details on what collision data is returned. Which movement method to use? @@ -196,7 +196,7 @@ from the Filesystem dock to the *Texture* property of the ``Sprite``). In the ``CollisionShape2D``'s *Shape* property, select "New RectangleShape2D" and size the rectangle to fit over the sprite image. -.. note:: See :ref:`doc_2d_movement` for examples of implementing 2D movement schemes. +.. note:: See `doc_2d_movement` for examples of implementing 2D movement schemes. Attach a script to the KinematicBody2D and add the following code: @@ -229,7 +229,7 @@ gdscript GDScript Run this scene and you'll see that ``move_and_collide()`` works as expected, moving the body along the velocity vector. Now let's see what happens when you add -some obstacles. Add a :ref:`StaticBody2D ` with a +some obstacles. Add a `StaticBody2D ` with a rectangular collision shape. For visibility, you can use a sprite, a Polygon2D, or turn on "Visible Collision Shapes" from the "Debug" menu. @@ -344,7 +344,7 @@ If you've downloaded the sample project, you can find this in "Platformer.tscn". For this example, we'll assume you have a level made of ``StaticBody2D`` objects. They can be any shape and size. In the sample project, we're using -:ref:`Polygon2D ` to create the platform shapes. +`Polygon2D ` to create the platform shapes. Here's the code for the player body: diff --git a/tutorials/platform/android/android_in_app_purchases.rst b/tutorials/platform/android/android_in_app_purchases.rst index b02f6d2..733fbb1 100644 --- a/tutorials/platform/android/android_in_app_purchases.rst +++ b/tutorials/platform/android/android_in_app_purchases.rst @@ -34,7 +34,7 @@ Usage Getting started *************** -If not already done, make sure you have enabled and successfully set up :ref:`Android Custom Builds `. +If not already done, make sure you have enabled and successfully set up `Android Custom Builds `. Grab the``GodotGooglePlayBilling`` plugin binary and config from the `releases page `__ and put both into `res://android/plugins`. The plugin should now show up in the Android export settings, where you can enable it. @@ -121,7 +121,7 @@ Check if the user purchased an item *********************************** To get all purchases, call ``queryPurchases``. Unlike most of the other functions, ``queryPurchases`` is -a synchronous operation and returns a :ref:`Dictionary ` with a status code +a synchronous operation and returns a `Dictionary ` with a status code and either an array of purchases or an error message. Only active subscriptions and non-consumed one-time purchases are returned. Full example: diff --git a/tutorials/platform/android/android_plugin.rst b/tutorials/platform/android/android_plugin.rst index aaf01da..e8a385c 100644 --- a/tutorials/platform/android/android_plugin.rst +++ b/tutorials/platform/android/android_plugin.rst @@ -38,7 +38,7 @@ Since we previously did not version the Android plugin systems, the new one is n **Note:** In Godot 4.0, the previous system will be fully deprecated and removed. -As a prerequisite, make sure you understand how to set up a :ref:`custom build environment` for Android. +As a prerequisite, make sure you understand how to set up a `custom build environment` for Android. At its core, a Godot Android plugin is a `Android archive library `_ (*aar* archive file) with the following caveats: diff --git a/tutorials/platform/customizing_html5_shell.rst b/tutorials/platform/customizing_html5_shell.rst index 39c36b9..c37f79f 100644 --- a/tutorials/platform/customizing_html5_shell.rst +++ b/tutorials/platform/customizing_html5_shell.rst @@ -80,7 +80,7 @@ To be able to start the game, you need to write a script that initializes the en code. This process consists of three steps, though as shown most of them can be skipped depending on how much customization is needed (or be left to a default behavior). -See the :ref:`HTML5 shell class reference `, for the full list of methods and options available. +See the `HTML5 shell class reference `, for the full list of methods and options available. First, the engine must be loaded, then it needs to be initialized, and after this the project can finally be started. You can perform every of these steps manually and with great control. @@ -148,7 +148,7 @@ allows to test for a specific major version of WebGL. As the real executable file does not exist in the Web environment, the engine only stores a virtual filename formed from the base name of loaded engine files. This value affects the output of the -:ref:`OS.get_executable_path() ` method and defines the name of +`OS.get_executable_path() ` method and defines the name of the automatically started main pack. The :js:attr:`executable` override option can be used to override this value. diff --git a/tutorials/platform/html5_shell_classref.rst b/tutorials/platform/html5_shell_classref.rst index 1a52a65..63796be 100644 --- a/tutorials/platform/html5_shell_classref.rst +++ b/tutorials/platform/html5_shell_classref.rst @@ -14,7 +14,7 @@ Engine The ``Engine`` class provides methods for loading and starting exported projects on the Web. For default export settings, this is already part of the exported HTML page. To understand practical use of the ``Engine`` class, -see :ref:`Custom HTML page for Web export `. +see `Custom HTML page for Web export `. Static Methods ^^^^^^^^^^^^^^ @@ -258,7 +258,7 @@ Properties Specify a language code to select the proper localization for the game. The browser locale will be used if none is specified. See complete list of - :ref:`supported locales `. + `supported locales `. :type: string @@ -283,7 +283,7 @@ Properties The arguments to be passed as command line arguments on startup. - See :ref:`command line tutorial `. + See `command line tutorial `. **Note**: :js:meth:`startGame ` will always add the ``--main-pack`` argument. diff --git a/tutorials/platform/ios/ios_plugin.rst b/tutorials/platform/ios/ios_plugin.rst index 42f462e..57fc0af 100644 --- a/tutorials/platform/ios/ios_plugin.rst +++ b/tutorials/platform/ios/ios_plugin.rst @@ -52,7 +52,7 @@ To build an iOS plugin: - Download the Godot engine source from the `Godot GitHub page `_. - - Run SCons to generate headers. You can learn the process by reading :ref:`doc_compiling_for_ios`. You don't have to wait for compilation to complete to move forward as headers are generated before the engine starts to compile. + - Run SCons to generate headers. You can learn the process by reading `doc_compiling_for_ios`. You don't have to wait for compilation to complete to move forward as headers are generated before the engine starts to compile. - You should use the same header files for iOS plugins and for the iOS export template. diff --git a/tutorials/platform/mobile_rendering_limitations.rst b/tutorials/platform/mobile_rendering_limitations.rst index cedbf72..0b9f7a9 100644 --- a/tutorials/platform/mobile_rendering_limitations.rst +++ b/tutorials/platform/mobile_rendering_limitations.rst @@ -5,11 +5,11 @@ Mobile rendering limitations .. seealso:: - The general :ref:`doc_3d_rendering_limitations` also apply to mobile platforms. + The general `doc_3d_rendering_limitations` also apply to mobile platforms. To improve out-of-the-box performance on mobile devices, Godot automatically uses low-end-friendly settings by default on both Android and iOS. These are configured -by project settings with a ``.mobile`` :ref:`feature tag ` suffix. +by project settings with a ``.mobile`` `feature tag ` suffix. One of the most notable changes on mobile that will affect 3D projects is that lighting is done per-vertex instead of per-pixel. This improves performance a @@ -55,7 +55,7 @@ The following project settings have mobile-specific overrides: | *GLES3 only:* ``rendering/quality/reflections/texture_array_reflections`` | ``true`` | ``false`` | +---------------------------------------------------------------------------+-----------------+--------------------+ -See the :ref:`ProjectSettings class documentation ` +See the `ProjectSettings class documentation ` for more information on those setting overrides. If you're only targeting mobile platforms in your project, consider changing the diff --git a/tutorials/plugins/editor/import_plugins.rst b/tutorials/plugins/editor/import_plugins.rst index d488e95..ef2cc88 100644 --- a/tutorials/plugins/editor/import_plugins.rst +++ b/tutorials/plugins/editor/import_plugins.rst @@ -4,7 +4,7 @@ Import plugins ============== .. note:: This tutorial assumes you already know how to make generic plugins. If - in doubt, refer to the :ref:`doc_making_plugins` page. This also + in doubt, refer to the `doc_making_plugins` page. This also assumes you are acquainted with Godot's import system. Introduction @@ -66,10 +66,10 @@ when needed: When this plugin is activated, it will create a new instance of the import plugin (which we'll soon make) and add it to the editor using the -:ref:`add_import_plugin() ` method. We store +`add_import_plugin() ` method. We store a reference to it in a class member ``import_plugin`` so we can refer to it later when removing it. The -:ref:`remove_import_plugin() ` method is +`remove_import_plugin() ` method is called when the plugin is deactivated to clean up the memory and let the editor know the import plugin isn't available anymore. @@ -81,7 +81,7 @@ The EditorImportPlugin class ---------------------------- The main character of the show is the -:ref:`EditorImportPlugin class `. It is responsible for +`EditorImportPlugin class `. It is responsible for implementing the methods that are called by Godot when it needs to know how to deal with files. @@ -98,7 +98,7 @@ Let's begin to code our plugin, one method at time: return "demos.sillymaterial" The first method is the -:ref:`get_importer_name()`. This is a +`get_importer_name()`. This is a unique name for your plugin that is used by Godot to know which import was used in a certain file. When the files needs to be reimported, the editor will know which plugin to call. @@ -108,7 +108,7 @@ which plugin to call. func get_visible_name(): return "Silly Material" -The :ref:`get_visible_name()` method is +The `get_visible_name()` method is responsible for returning the name of the type it imports and it will be shown to the user in the Import dock. @@ -122,7 +122,7 @@ descriptive name for your plugin. return ["mtxt"] Godot's import system detects file types by their extension. In the -:ref:`get_recognized_extensions()` +`get_recognized_extensions()` method you return an array of strings to represent each extension that this plugin can understand. If an extension is recognized by more than one plugin, the user can select which one to use when importing the files. @@ -157,7 +157,7 @@ The imported resource has a specific type, so the editor can know which property slot it belongs to. This allows drag and drop from the FileSystem dock to a property in the Inspector. -In our case it's a :ref:`class_SpatialMaterial`, which can be applied to 3D +In our case it's a `class_SpatialMaterial`, which can be applied to 3D objects. .. note:: If you need to import different types from the same extension, you @@ -196,7 +196,7 @@ plugin: func get_preset_count(): return Presets.size() -The :ref:`get_preset_count() ` method +The `get_preset_count() ` method returns the amount of presets that this plugins defines. We only have one preset now, but we can make this method future-proof by returning the size of our ``Presets`` enumeration. @@ -212,7 +212,7 @@ now, but we can make this method future-proof by returning the size of our Here we have the -:ref:`get_preset_name() ` method, which +`get_preset_name() ` method, which gives names to the presets as they will be presented to the user, so be sure to use short and clear names. @@ -237,7 +237,7 @@ you do this you have to be careful when you add more presets. return [] This is the method which defines the available options. -:ref:`get_import_options() ` returns +`get_import_options() ` returns an array of dictionaries, and each dictionary contains a few keys that are checked to customize the option as its shown to the user. The following table shows the possible keys: @@ -249,11 +249,11 @@ shows the possible keys: +-------------------+------------+----------------------------------------------------------------------------------------------------------+ | ``default_value`` | Any | The default value of the option for this preset. | +-------------------+------------+----------------------------------------------------------------------------------------------------------+ -| ``property_hint`` | Enum value | One of the :ref:`PropertyHint ` values to use as hint. | +| ``property_hint`` | Enum value | One of the `PropertyHint ` values to use as hint. | +-------------------+------------+----------------------------------------------------------------------------------------------------------+ | ``hint_string`` | String | The hint text of the property. The same as you'd add in the ``export`` statement in GDScript. | +-------------------+------------+----------------------------------------------------------------------------------------------------------+ -| ``usage`` | Enum value | One of the :ref:`PropertyUsageFlags ` values to define the usage. | +| ``usage`` | Enum value | One of the `PropertyUsageFlags ` values to define the usage. | +-------------------+------------+----------------------------------------------------------------------------------------------------------+ The ``name`` and ``default_value`` keys are **mandatory**, the rest are optional. @@ -275,7 +275,7 @@ of options first and then change it based on the preset. return true For the -:ref:`get_option_visibility() ` +`get_option_visibility() ` method, we simply return ``true`` because all of our options (i.e. the single one we defined) are visible all the time. @@ -286,7 +286,7 @@ The ``import`` method --------------------- The heavy part of the process, responsible for converting the files into -resources, is covered by the :ref:`import() ` +resources, is covered by the `import() ` method. Our sample code is a bit long, so let's split in a few parts: :: @@ -302,7 +302,7 @@ method. Our sample code is a bit long, so let's split in a few parts: file.close() The first part of our import method opens and reads the source file. We use the -:ref:`File ` class to do that, passing the ``source_file`` +`File ` class to do that, passing the ``source_file`` parameter which is provided by the editor. If there's an error when opening the file, we return it to let the editor know @@ -324,7 +324,7 @@ This code takes the line of the file it read before and splits it in pieces that are separated by a comma. If there are more or less than the three values, it considers the file invalid and reports an error. -Then it creates a new :ref:`Color ` variable and sets its values +Then it creates a new `Color ` variable and sets its values according to the input file. If the ``use_red_anyway`` option is enabled, then it sets the color as a pure red instead. @@ -333,7 +333,7 @@ it sets the color as a pure red instead. var material = SpatialMaterial.new() material.albedo_color = color -This part makes a new :ref:`SpatialMaterial ` that is the +This part makes a new `SpatialMaterial ` that is the imported resource. We create a new instance of it and then set its albedo color as the value we got before. @@ -344,12 +344,12 @@ as the value we got before. This is the last part and quite an important one, because here we save the made resource to the disk. The path of the saved file is generated and informed by the editor via the ``save_path`` parameter. Note that this comes **without** the -extension, so we add it using :ref:`string formatting `. For +extension, so we add it using `string formatting `. For this we call the ``get_save_extension`` method that we defined earlier, so we can be sure that they won't get out of sync. We also return the result from the -:ref:`ResourceSaver.save() ` method, so if there's an +`ResourceSaver.save() ` method, so if there's an error in this step, the editor will know about it. Platform variants and generated files @@ -362,7 +362,7 @@ method. Both of them are arrays that you can fill with information. The ``r_platform_variants`` argument is used if you need to import the resource differently depending on the target platform. While it's called *platform* -variants, it is based on the presence of :ref:`feature tags `, +variants, it is based on the presence of `feature tags `, so even the same platform can have multiple variants depending on the setup. To import a platform variant, you need to save it with the feature tag before diff --git a/tutorials/plugins/editor/inspector_plugins.rst b/tutorials/plugins/editor/inspector_plugins.rst index bf8eeb9..70e675e 100644 --- a/tutorials/plugins/editor/inspector_plugins.rst +++ b/tutorials/plugins/editor/inspector_plugins.rst @@ -9,8 +9,8 @@ resources, although you can use the feature to change the inspector widgets for built-in types. You can design custom controls for specific properties, entire objects, and even separate controls associated with particular datatypes. -This guide explains how to use the :ref:`class_EditorInspectorPlugin` and -:ref:`class_EditorProperty` classes to create a custom interface for integers, +This guide explains how to use the `class_EditorInspectorPlugin` and +`class_EditorProperty` classes to create a custom interface for integers, replacing the default behavior with a button that generates random values between 0 and 99. @@ -25,13 +25,13 @@ Setting up your plugin Create a new empty plugin to get started. -.. seealso:: See :ref:`doc_making_plugins` guide to set up your new plugin. +.. seealso:: See `doc_making_plugins` guide to set up your new plugin. Let's assume you've called your plugin folder ``my_inspector_plugin``. If so, you should end up with a new ``addons/my_inspector_plugin`` folder that contains two files: ``plugin.cfg`` and ``plugin.gd``. -As before, ``plugin.gd`` is a script extending :ref:`class_EditorPlugin` and you +As before, ``plugin.gd`` is a script extending `class_EditorPlugin` and you need to introduce new code for its ``_enter_tree`` and ``_exit_tree`` methods. To set up your inspector plugin, you must load its script, then create and add the instance by calling ``add_inspector_plugin()``. If the plugin is disabled, @@ -65,14 +65,14 @@ Interacting with the inspector ------------------------------ To interact with the inspector dock, your ``MyInspectorPlugin.gd`` script must -extend the :ref:`class_EditorInspectorPlugin` class. This class provides several +extend the `class_EditorInspectorPlugin` class. This class provides several virtual methods that affect how the inspector handles properties. To have any effect at all, the script must implement the ``can_handle()`` -method. This function is called for each edited :ref:`class_Object` and must +method. This function is called for each edited `class_Object` and must return ``true`` if this plugin should handle the object or its properties. -.. note:: This includes any :ref:`class_Resource` attached to the object. +.. note:: This includes any `class_Resource` attached to the object. You can implement four other methods to add controls to the inspector at specific positions. The ``parse_begin()`` and ``parse_end()`` methods are called @@ -84,7 +84,7 @@ As the editor parses the object, it calls the ``parse_category()`` and ``parse_property()`` methods. There, in addition to ``add_custom_control()``, you can call both ``add_property_editor()`` and ``add_property_editor_for_multiple_properties()``. Use these last two methods to -specifically add :ref:`class_EditorProperty`-based controls. +specifically add `class_EditorProperty`-based controls. gdscript GDScript @@ -117,12 +117,12 @@ gdscript GDScript Adding an interface to edit properties -------------------------------------- -The :ref:`class_EditorProperty` class is a special type of :ref:`class_Control` +The `class_EditorProperty` class is a special type of `class_Control` that can interact with the inspector dock's edited objects. It doesn't display anything but can house any other control nodes, including complex scenes. There are three essential parts to the script extending -:ref:`class_EditorProperty`: +`class_EditorProperty`: 1. You must define the ``_init()`` method to set up the control nodes' structure. @@ -190,5 +190,5 @@ gdscript GDScript ``` Using the example code above you should be able to make a custom widget that -replaces the default :ref:`class_SpinBox` control for integers with a -:ref:`class_Button` that generates random values. +replaces the default `class_SpinBox` control for integers with a +`class_Button` that generates random values. diff --git a/tutorials/plugins/editor/making_main_screen_plugins.rst b/tutorials/plugins/editor/making_main_screen_plugins.rst index f8d5ba7..81a67dd 100644 --- a/tutorials/plugins/editor/making_main_screen_plugins.rst +++ b/tutorials/plugins/editor/making_main_screen_plugins.rst @@ -6,7 +6,7 @@ Making main screen plugins What this tutorial covers ------------------------- -As seen in the :ref:`doc_making_plugins` page, making a basic plugin that +As seen in the `doc_making_plugins` page, making a basic plugin that extends the editor is fairly easy. Main screen plugins allow you to create new UIs in the central part of the editor, which appear next to the "2D", "3D", "Script", and "AssetLib" buttons. Such editor plugins are @@ -85,7 +85,7 @@ Add a script to the button like this: print("Hello from the main screen plugin!") Then connect the "pressed" signal to itself. If you need help with signals, -see the :ref:`doc_signals` article. +see the `doc_signals` article. We are done with the main screen panel. Save the scene as ``main_panel.tscn``. diff --git a/tutorials/plugins/editor/making_plugins.rst b/tutorials/plugins/editor/making_plugins.rst index 06c4c81..27790d3 100644 --- a/tutorials/plugins/editor/making_plugins.rst +++ b/tutorials/plugins/editor/making_plugins.rst @@ -81,7 +81,7 @@ The script file Upon creation of the plugin, the dialog will automatically open the EditorPlugin script for you. The script has two requirements that you cannot change: it must be a ``tool`` script, or else it will not load properly in the -editor, and it must inherit from :ref:`class_EditorPlugin`. +editor, and it must inherit from `class_EditorPlugin`. .. warning:: @@ -91,8 +91,8 @@ editor, and it must inherit from :ref:`class_EditorPlugin`. It's important to deal with initialization and clean-up of resources. A good practice is to use the virtual function -:ref:`_enter_tree() ` to initialize your plugin and -:ref:`_exit_tree() ` to clean it up. Thankfully, +`_enter_tree() ` to initialize your plugin and +`_exit_tree() ` to clean it up. Thankfully, the dialog generates these callbacks for you. Your script should look something like this: @@ -130,20 +130,20 @@ custom behavior. Nodes added via an EditorPlugin are "CustomType" nodes. While they work with any scripting language, they have fewer features than - :ref:`the Script Class system `. If you + `the Script Class system `. If you are writing GDScript or NativeScript, we recommend using Script Classes instead. To create a new node type, you can use the function -:ref:`add_custom_type() ` from the -:ref:`class_EditorPlugin` class. This function can add new types to the editor +`add_custom_type() ` from the +`class_EditorPlugin` class. This function can add new types to the editor (nodes or resources). However, before you can create the type, you need a script that will act as the logic for the type. While that script doesn't have to use the ``tool`` keyword, it can be added so the script runs in the editor. For this tutorial, we'll create a simple button that prints a message when clicked. For that, we'll need a simple script that extends from -:ref:`class_Button`. It could also extend -:ref:`class_BaseButton` if you prefer: +`class_Button`. It could also extend +`class_BaseButton` if you prefer: gdscript GDScript @@ -227,14 +227,14 @@ gdscript GDScript ``` Then create the script ``custom_dock.gd`` in the same folder. Fill it with the -:ref:`template we've seen before ` to get a +`template we've seen before ` to get a good start. Since we're trying to add a new custom dock, we need to create the contents of the dock. This is nothing more than a standard Godot scene: just create a new scene in the editor then edit it. -For an editor dock, the root node **must** be a :ref:`Control ` +For an editor dock, the root node **must** be a `Control ` or one of its child classes. For this tutorial, you can create a single button. The name of the root node will also be the name that appears on the dock tab, so be sure to give it a short and descriptive name. @@ -244,8 +244,8 @@ Also, don't forget to add some text to your button. Save this scene as ``my_dock.tscn``. Now, we need to grab the scene we created then add it as a dock in the editor. For this, you can rely on the function -:ref:`add_control_to_dock() ` from the -:ref:`EditorPlugin ` class. +`add_control_to_dock() ` from the +`EditorPlugin ` class. You need to select a dock position and define the control to add (which is the scene you just created). Don't forget to @@ -318,7 +318,7 @@ Registering autoloads/singletons in plugins ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ It is possible for editor plugins to automatically register -:ref:`autoloads ` when the plugin is enabled. +`autoloads ` when the plugin is enabled. This also includes unregistering the autoload when the plugin is disabled. This makes setting up plugins faster for users, as they no longer have to manually diff --git a/tutorials/plugins/editor/spatial_gizmos.rst b/tutorials/plugins/editor/spatial_gizmos.rst index 0c059b0..983f5ff 100644 --- a/tutorials/plugins/editor/spatial_gizmos.rst +++ b/tutorials/plugins/editor/spatial_gizmos.rst @@ -14,13 +14,13 @@ gizmos. The first option works well for simple gizmos and creates less clutter i your plugin structure, while the second one will let you store some per-gizmo data. .. note:: This tutorial assumes you already know how to make generic plugins. If - in doubt, refer to the :ref:`doc_making_plugins` page. + in doubt, refer to the `doc_making_plugins` page. The EditorSpatialGizmoPlugin ---------------------------- Regardless of the approach we choose, we will need to create a new -:ref:`EditorSpatialGizmoPlugin `. This will allow +`EditorSpatialGizmoPlugin `. This will allow us to set a name for the new gizmo type and define other behaviors such as whether the gizmo can be hidden or not. @@ -56,7 +56,7 @@ This would be a basic setup: remove_spatial_gizmo_plugin(gizmo_plugin) -For simple gizmos, just inheriting :ref:`EditorSpatialGizmoPlugin ` +For simple gizmos, just inheriting `EditorSpatialGizmoPlugin ` is enough. If you want to store some per-gizmo data or you are porting a Godot 3.0 gizmo to 3.1+, you should go with the second approach. @@ -64,7 +64,7 @@ to 3.1+, you should go with the second approach. Simple approach --------------- -The first step is to, in our custom gizmo plugin, override the :ref:`has_gizmo()` +The first step is to, in our custom gizmo plugin, override the `has_gizmo()` method so that it returns ``true`` when the spatial parameter is of our target type. :: @@ -78,7 +78,7 @@ method so that it returns ``true`` when the spatial parameter is of our target t # ... -Then we can override methods like :ref:`redraw()` +Then we can override methods like `redraw()` or all the handle related ones. :: @@ -113,7 +113,7 @@ or all the handle related ones. # ... Note that we created a material in the `_init` method, and retrieved it in the `redraw` -method using :ref:`get_material()`. This +method using `get_material()`. This method retrieves one of the material's variants depending on the state of the gizmo (selected and/or editable). @@ -159,18 +159,18 @@ So the final plugin would look somewhat like this: # (get_handle_name(), get_handle_value(), commit_handle()...). Note that we just added some handles in the redraw method, but we still need to implement -the rest of handle-related callbacks in :ref:`EditorSpatialGizmoPlugin ` +the rest of handle-related callbacks in `EditorSpatialGizmoPlugin ` to get properly working handles. Alternative approach -------------------- -In some cases we want to provide our own implementation of :ref:`EditorSpatialGizmo`, +In some cases we want to provide our own implementation of `EditorSpatialGizmo`, maybe because we want to have some state stored in each gizmo or because we are porting an old gizmo plugin and we don't want to go through the rewriting process. In these cases all we need to do is, in our new gizmo plugin, override -:ref:`create_gizmo()`, so it returns our custom gizmo implementation +`create_gizmo()`, so it returns our custom gizmo implementation for the Spatial nodes we want to target. :: @@ -195,7 +195,7 @@ for the Spatial nodes we want to target. return null This way all the gizmo logic and drawing methods can be implemented in a new class extending -:ref:`EditorSpatialGizmo`, like so: +`EditorSpatialGizmo`, like so: :: @@ -233,5 +233,5 @@ This way all the gizmo logic and drawing methods can be implemented in a new cla # (get_handle_name(), get_handle_value(), commit_handle()...). Note that we just added some handles in the redraw method, but we still need to implement -the rest of handle-related callbacks in :ref:`EditorSpatialGizmo` +the rest of handle-related callbacks in `EditorSpatialGizmo` to get properly working handles. diff --git a/tutorials/plugins/editor/visual_shader_plugins.rst b/tutorials/plugins/editor/visual_shader_plugins.rst index 84a2051..917988d 100644 --- a/tutorials/plugins/editor/visual_shader_plugins.rst +++ b/tutorials/plugins/editor/visual_shader_plugins.rst @@ -3,7 +3,7 @@ Visual Shader plugins ===================== -Visual Shader plugins are used to create custom :ref:`class_VisualShader` nodes +Visual Shader plugins are used to create custom `class_VisualShader` nodes in GDScript. The creation process is different from usual editor plugins. You do not need to @@ -15,11 +15,11 @@ This short tutorial will explain how to make a Perlin-3D noise node (original code from this `GPU noise shaders plugin `_. -Create a Sprite and assign a :ref:`class_ShaderMaterial` to its material slot: +Create a Sprite and assign a `class_ShaderMaterial` to its material slot: .. image:: img/visual_shader_plugins_start.png -Assign :ref:`class_VisualShader` to the shader slot of the material: +Assign `class_VisualShader` to the shader slot of the material: .. image:: img/visual_shader_plugins_start2.png @@ -27,7 +27,7 @@ Don't forget to change its mode to "CanvasItem" (if you are using a Sprite): .. image:: img/visual_shader_plugins_start3.png -Create a script which derives from :ref:`class_VisualShaderNodeCustom`. This is +Create a script which derives from `class_VisualShaderNodeCustom`. This is all you need to initialize your plugin. :: diff --git a/tutorials/plugins/running_code_in_the_editor.rst b/tutorials/plugins/running_code_in_the_editor.rst index 473b4bb..727c030 100644 --- a/tutorials/plugins/running_code_in_the_editor.rst +++ b/tutorials/plugins/running_code_in_the_editor.rst @@ -21,7 +21,7 @@ You can use it for doing many things, but it is mostly useful in level design fo with caveats, as the editor does not include protections for potential misuse of ``tool`` scripts. Be **extremely** cautious when manipulating the scene tree, especially via - :ref:`Node.queue_free`, as it can cause + `Node.queue_free`, as it can cause crashes if you free a node while the editor runs logic involving it. How to use it @@ -136,10 +136,10 @@ Instancing scenes You can instantiate packed scenes normally and add them to the scene currently opened in the editor. By default, nodes or scenes added with -:ref:`Node.add_child(node) ` are **not** visible +`Node.add_child(node) ` are **not** visible in the Scene tree dock and are **not** persisted to disk. If you wish the node or scene to be visible in the scene tree dock and persisted to disk when saving -the scene, you need to set the child node's :ref:`owner ` +the scene, you need to set the child node's `owner ` property to the currently edited scene root. If you are using ``tool``: @@ -156,7 +156,7 @@ gdscript GDScript node.set_owner(get_tree().edited_scene_root) ``` -If you are using :ref:`EditorScript`: +If you are using `EditorScript`: gdscript GDScript diff --git a/tutorials/rendering/multiple_resolutions.rst b/tutorials/rendering/multiple_resolutions.rst index f13fdfc..5f68702 100644 --- a/tutorials/rendering/multiple_resolutions.rst +++ b/tutorials/rendering/multiple_resolutions.rst @@ -90,7 +90,7 @@ Resizing There are several types of devices, with several types of screens, which in turn have different pixel density and resolutions. Handling all of them can be a lot of work, so Godot tries to make the developer's life a -little easier. The :ref:`Viewport ` +little easier. The `Viewport ` node has several functions to handle resizing, and the root node of the scene tree is always a viewport (scenes loaded are instanced as a child of it, and it can always be accessed by calling @@ -119,7 +119,7 @@ the resolution of the window or screen. The animations below use a "base size" of just 16×9 pixels to demonstrate the effect of different stretch modes. A single sprite, also 16×9 pixels in size, covers the entire viewport, and a diagonal -:ref:`Line2D ` is added on top of it: +`Line2D ` is added on top of it: .. image:: img/stretch_demo_scene.png @@ -143,7 +143,7 @@ demonstrate the effect of different stretch modes. A single sprite, also .. image:: img/stretch_2d_expand.gif - **Stretch Mode = Viewport**: Viewport scaling means that the size of - the root :ref:`Viewport ` is set precisely to the + the root `Viewport ` is set precisely to the base size specified in the Project Settings' **Display** section. The scene is rendered to this viewport first. Finally, this viewport is scaled to fit the screen (taking the **Stretch Aspect** setting into @@ -191,7 +191,7 @@ to the region outside the blue frame you see in the 2D editor. This is usually the best option for creating GUIs or HUDs that scale, so some controls can be anchored to the bottom - (:ref:`doc_size_and_anchors`). + (`doc_size_and_anchors`). .. image:: img/stretch_viewport_keep_width.gif @@ -250,7 +250,7 @@ From scripts To configure stretching at runtime from a script, use the ``get_tree().set_screen_stretch()`` method (see -:ref:`SceneTree.set_screen_stretch() `). +`SceneTree.set_screen_stretch() `). Common use case scenarios ------------------------- @@ -272,7 +272,7 @@ Desktop game visuals at the cost of higher memory usage and file sizes. Note that this will make non-mipmapped textures grainy on low resolution devices, so make sure to follow the instructions described in - :ref:`doc_multiple_resolutions_reducing_aliasing_on_downsampling`. + `doc_multiple_resolutions_reducing_aliasing_on_downsampling`. - Set the stretch mode to ``2d``. - Set the stretch aspect to ``expand``. This allows for supporting multiple aspect ratios and makes better use of tall smartphone displays (such as 18:9 or 19:9 aspect ratios). @@ -319,7 +319,7 @@ to change the display orientation project setting. barely visible given the small size of smartphone displays. Note that this will make non-mipmapped textures grainy on low resolution devices, so make sure to follow the instructions described in - :ref:`doc_multiple_resolutions_reducing_aliasing_on_downsampling`. + `doc_multiple_resolutions_reducing_aliasing_on_downsampling`. - Set the stretch mode to ``2d``. - Set the stretch aspect to ``expand``. This allows for supporting multiple aspect ratios and makes better use of tall smartphone displays (such as 18:9 or 19:9 aspect ratios). @@ -337,7 +337,7 @@ Mobile game in portrait mode barely visible given the small size of smartphone displays. Note that this will make non-mipmapped textures grainy on low resolution devices, so make sure to follow the instructions described in - :ref:`doc_multiple_resolutions_reducing_aliasing_on_downsampling`. + `doc_multiple_resolutions_reducing_aliasing_on_downsampling`. - Set **Display > Window > Handheld > Orientation** to ``portrait``. - Set the stretch mode to ``2d``. - Set the stretch aspect to ``expand``. This allows for supporting multiple aspect ratios @@ -407,7 +407,7 @@ Handling aspect ratios Once scaling for different resolutions is accounted for, make sure that your *user interface* also scales for different aspect ratios. This can be -done using :ref:`anchors ` and/or :ref:`containers +done using `anchors ` and/or `containers `. Field of view scaling diff --git a/tutorials/rendering/viewports.rst b/tutorials/rendering/viewports.rst index 5f058a2..9e67e6a 100644 --- a/tutorials/rendering/viewports.rst +++ b/tutorials/rendering/viewports.rst @@ -6,23 +6,23 @@ Using Viewports Introduction ------------ -Think of a :ref:`Viewport ` as a screen onto which the game is projected. In order +Think of a `Viewport ` as a screen onto which the game is projected. In order to see the game, we need to have a surface on which to draw it; that surface is -the Root :ref:`Viewport `. +the Root `Viewport `. .. image:: img/viewportnode.png -:ref:`Viewports ` can also be added to the scene so that there -are multiple surfaces to draw on. When we are drawing to a :ref:`Viewport ` +`Viewports ` can also be added to the scene so that there +are multiple surfaces to draw on. When we are drawing to a `Viewport ` that is not the Root, we call it a render target. We can access the contents -of a render target by accessing its corresponding :ref:`texture `. -By using a :ref:`Viewport ` as a render target, +of a render target by accessing its corresponding `texture `. +By using a `Viewport ` as a render target, we can either render multiple scenes simultaneously or we can render to -a :ref:`texture ` which is applied to an object in the scene, for example a dynamic +a `texture ` which is applied to an object in the scene, for example a dynamic skybox. -:ref:`Viewports ` have a variety of use cases, including: +`Viewports ` have a variety of use cases, including: - Rendering 3D objects within a 2D game - Rendering 2D elements in a 3D game @@ -37,42 +37,42 @@ what to do with the resulting texture. Input ----- -:ref:`Viewports ` are also responsible for delivering properly adjusted and +`Viewports ` are also responsible for delivering properly adjusted and scaled input events to all their children nodes. Typically, input is received by the -nearest :ref:`Viewport ` in the tree, but you can set :ref:`Viewports ` not to receive input by checking -'Disable Input' to 'on'; this will allow the next nearest :ref:`Viewport ` in the tree to capture +nearest `Viewport ` in the tree, but you can set `Viewports ` not to receive input by checking +'Disable Input' to 'on'; this will allow the next nearest `Viewport ` in the tree to capture the input. .. image:: img/input.png -For more information on how Godot handles input, please read the :ref:`Input Event Tutorial`. +For more information on how Godot handles input, please read the `Input Event Tutorial`. Listener -------- Godot supports 3D sound (in both 2D and 3D nodes); more on this can be -found in the :ref:`Audio Streams Tutorial`. For this type of sound to be -audible, the :ref:`Viewport ` needs to be enabled as a listener (for 2D or 3D). -If you are using a custom :ref:`Viewport ` to display your :ref:`World `, don't forget +found in the `Audio Streams Tutorial`. For this type of sound to be +audible, the `Viewport ` needs to be enabled as a listener (for 2D or 3D). +If you are using a custom `Viewport ` to display your `World `, don't forget to enable this! Cameras (2D & 3D) ----------------- -When using a :ref:`Camera ` / -:ref:`Camera2D `, cameras will always display on the -closest parent :ref:`Viewport ` (going towards the root). For example, in the +When using a `Camera ` / +`Camera2D `, cameras will always display on the +closest parent `Viewport ` (going towards the root). For example, in the following hierarchy: .. image:: img/cameras.png -CameraA will display on the Root :ref:`Viewport ` and it will draw MeshA. CameraB -will be captured by the :ref:`Viewport ` Node along with MeshB. Even though MeshB is in the scene -hierarchy, it will still not be drawn to the Root :ref:`Viewport `. Similarly MeshA will not -be visible from the :ref:`Viewport ` node because :ref:`Viewport ` nodes only +CameraA will display on the Root `Viewport ` and it will draw MeshA. CameraB +will be captured by the `Viewport ` Node along with MeshB. Even though MeshB is in the scene +hierarchy, it will still not be drawn to the Root `Viewport `. Similarly MeshA will not +be visible from the `Viewport ` node because `Viewport ` nodes only capture nodes below them in the hierarchy. -There can only be one active camera per :ref:`Viewport `, so if there is more +There can only be one active camera per `Viewport `, so if there is more than one, make sure that the desired one has the "current" property set, or make it the current camera by calling: @@ -81,18 +81,18 @@ or make it the current camera by calling: camera.make_current() By default, cameras will render all objects in their world. In 3D, cameras can use their -:ref:`cull_mask ` property combined with the -:ref:`VisualInstance's ` :ref:`layer ` +`cull_mask ` property combined with the +`VisualInstance's ` `layer ` property to restrict which objects are rendered. Scale & stretching ------------------ -:ref:`Viewports ` have a "size" property, which represents the size of the :ref:`Viewport ` -in pixels. For :ref:`Viewports ` which are children of :ref:`ViewportContainers `, +`Viewports ` have a "size" property, which represents the size of the `Viewport ` +in pixels. For `Viewports ` which are children of `ViewportContainers `, these values are overridden, but for all others, this sets their resolution. -It is also possible to scale the 2D content and make the :ref:`Viewport ` resolution +It is also possible to scale the 2D content and make the `Viewport ` resolution different from the one specified in size, by calling: :: @@ -100,40 +100,40 @@ different from the one specified in size, by calling: viewport.set_size_override(true, Vector2(width, height)) # Custom size for 2D. viewport.set_size_override_stretch(true) # Enable stretch for custom size. -The root :ref:`Viewport ` uses this for the stretch options in the project -settings. For more information on scaling and stretching visit the :ref:`Multiple Resolutions Tutorial ` +The root `Viewport ` uses this for the stretch options in the project +settings. For more information on scaling and stretching visit the `Multiple Resolutions Tutorial ` Worlds ------ -For 3D, a :ref:`Viewport ` will contain a :ref:`World `. This +For 3D, a `Viewport ` will contain a `World `. This is basically the universe that links physics and rendering together. -Spatial-based nodes will register using the :ref:`World ` of the closest -:ref:`Viewport `. By default, newly created :ref:`Viewports ` do not contain a :ref:`World ` but -use the same as their parent :ref:`Viewport ` (the root :ref:`Viewport ` always contains a -:ref:`World `, which is the one objects are rendered to by default). A :ref:`World ` can -be set in a :ref:`Viewport ` using the "world" property, and that will separate -all children nodes of that :ref:`Viewport ` from interacting with the parent -:ref:`Viewport's ` :ref:`World `. This is especially useful in scenarios where, for +Spatial-based nodes will register using the `World ` of the closest +`Viewport `. By default, newly created `Viewports ` do not contain a `World ` but +use the same as their parent `Viewport ` (the root `Viewport ` always contains a +`World `, which is the one objects are rendered to by default). A `World ` can +be set in a `Viewport ` using the "world" property, and that will separate +all children nodes of that `Viewport ` from interacting with the parent +`Viewport's ` `World `. This is especially useful in scenarios where, for example, you might want to show a separate character in 3D imposed over the game (like in StarCraft). -As a helper for situations where you want to create :ref:`Viewports ` that -display single objects and don't want to create a :ref:`World `, :ref:`Viewport ` has -the option to use its own :ref:`World `. This is useful when you want to -instance 3D characters or objects in a 2D :ref:`World `. +As a helper for situations where you want to create `Viewports ` that +display single objects and don't want to create a `World `, `Viewport ` has +the option to use its own `World `. This is useful when you want to +instance 3D characters or objects in a 2D `World `. -For 2D, each :ref:`Viewport ` always contains its own :ref:`World2D `. +For 2D, each `Viewport ` always contains its own `World2D `. This suffices in most cases, but in case sharing them may be desired, it -is possible to do so by setting the :ref:`Viewport's ` :ref:`World2D ` manually. +is possible to do so by setting the `Viewport's ` `World2D ` manually. For an example of how this works, see the demo projects `3D in 2D `_ and `2D in 3D `_ respectively. Capture ------- -It is possible to query a capture of the :ref:`Viewport ` contents. For the root -:ref:`Viewport `, this is effectively a screen capture. This is done with the +It is possible to query a capture of the `Viewport ` contents. For the root +`Viewport `, this is effectively a screen capture. This is done with the following code: :: @@ -149,7 +149,7 @@ following code: # Set Sprite Texture. $sprite.texture = tex -But if you use this in ``_ready()`` or from the first frame of the :ref:`Viewport's ` initialization, +But if you use this in ``_ready()`` or from the first frame of the `Viewport's ` initialization, you will get an empty texture because there is nothing to get as texture. You can deal with it using (for example): @@ -162,33 +162,33 @@ it using (for example): Viewport Container ------------------ -If the :ref:`Viewport ` is a child of a :ref:`ViewportContainer `, it will become active and display anything it has inside. The layout looks like this: +If the `Viewport ` is a child of a `ViewportContainer `, it will become active and display anything it has inside. The layout looks like this: .. image:: img/container.png -The :ref:`Viewport ` will cover the area of its parent :ref:`ViewportContainer ` completely -if :ref:`Stretch` is set to ``true`` in :ref:`ViewportContainer `. -Note: The size of the :ref:`ViewportContainer ` cannot be smaller than the size of the :ref:`Viewport `. +The `Viewport ` will cover the area of its parent `ViewportContainer ` completely +if `Stretch` is set to ``true`` in `ViewportContainer `. +Note: The size of the `ViewportContainer ` cannot be smaller than the size of the `Viewport `. Rendering --------- -Due to the fact that the :ref:`Viewport ` is an entryway into another rendering surface, it exposes a few +Due to the fact that the `Viewport ` is an entryway into another rendering surface, it exposes a few rendering properties that can be different from the project settings. The first is MSAA; you can -choose to use a different level of MSAA for each :ref:`Viewport `; the default behavior is DISABLED. -You can also set the :ref:`Viewport ` to use HDR, HDR is very useful for when you want to store values in the texture that are outside the range 0.0 - 1.0. +choose to use a different level of MSAA for each `Viewport `; the default behavior is DISABLED. +You can also set the `Viewport ` to use HDR, HDR is very useful for when you want to store values in the texture that are outside the range 0.0 - 1.0. -If you know how the :ref:`Viewport ` is going to be used, you can set its Usage to either 3D or 2D. Godot will then -restrict how the :ref:`Viewport ` is drawn to in accordance with your choice; default is 3D. -The 2D usage mode is slightly faster and uses less memory compared to the 3D one. It's a good idea to set the :ref:`Viewport `'s Usage property to 2D if your viewport doesn't render anything in 3D. +If you know how the `Viewport ` is going to be used, you can set its Usage to either 3D or 2D. Godot will then +restrict how the `Viewport ` is drawn to in accordance with your choice; default is 3D. +The 2D usage mode is slightly faster and uses less memory compared to the 3D one. It's a good idea to set the `Viewport `'s Usage property to 2D if your viewport doesn't render anything in 3D. .. note:: If you need to render 3D shadows in the viewport, make sure to set the viewport's *Shadow Atlas Size* property to a value higher than 0. Otherwise, shadows won't be rendered. For reference, the Project Settings define it to 4096 by default. -Godot also provides a way of customizing how everything is drawn inside :ref:`Viewports ` using “Debug Draw”. -Debug Draw allows you to specify one of four options for how the :ref:`Viewport ` will display things drawn +Godot also provides a way of customizing how everything is drawn inside `Viewports ` using “Debug Draw”. +Debug Draw allows you to specify one of four options for how the `Viewport ` will display things drawn inside it. Debug Draw is disabled by default. .. image:: img/default_scene.png @@ -218,8 +218,8 @@ Lastly, Wireframe draws the scene using only the edges of triangles in the meshe Render target ------------- -When rendering to a :ref:`Viewport `, whatever is inside will not be -visible in the scene editor. To display the contents, you have to draw the :ref:`Viewport's ` :ref:`ViewportTexture ` somewhere. +When rendering to a `Viewport `, whatever is inside will not be +visible in the scene editor. To display the contents, you have to draw the `Viewport's ` `ViewportTexture ` somewhere. This can be requested via code using (for example): :: @@ -232,17 +232,17 @@ Or it can be assigned in the editor by selecting "New ViewportTexture" .. image:: img/texturemenu.png -and then selecting the :ref:`Viewport ` you want to use. +and then selecting the `Viewport ` you want to use. .. image:: img/texturepath.png -Every frame, the :ref:`Viewport `'s texture is cleared away with the default clear color (or a transparent -color if :ref:`Transparent Bg` is set to ``true``). This can be changed by setting :ref:`Clear Mode` to Never or Next Frame. +Every frame, the `Viewport `'s texture is cleared away with the default clear color (or a transparent +color if `Transparent Bg` is set to ``true``). This can be changed by setting `Clear Mode` to Never or Next Frame. As the name implies, Never means the texture will never be cleared, while next frame will clear the texture on the next frame and then set itself to Never. -By default, re-rendering of the :ref:`Viewport ` happens when the -:ref:`Viewport `'s :ref:`ViewportTexture ` has been drawn in a frame. If visible, it will be +By default, re-rendering of the `Viewport ` happens when the +`Viewport `'s `ViewportTexture ` has been drawn in a frame. If visible, it will be rendered; otherwise, it will not. This behavior can be changed to manual rendering (once), or always render, no matter if visible or not. This flexibility allows users to render an image once and then use the texture without diff --git a/tutorials/scripting/change_scenes_manually.rst b/tutorials/scripting/change_scenes_manually.rst index 8d4fa08..6aa56f8 100644 --- a/tutorials/scripting/change_scenes_manually.rst +++ b/tutorials/scripting/change_scenes_manually.rst @@ -4,7 +4,7 @@ Change scenes manually ====================== Sometimes it helps to have more control over how one swaps scenes around. -As mentioned above, a :ref:`Viewport `'s child nodes +As mentioned above, a `Viewport `'s child nodes will render to the image it generates. This holds true even for nodes outside of the "current" scene. Autoloads fall into this category, but so do scenes which one instances and adds to the tree at runtime: @@ -22,13 +22,13 @@ gdscript GDScript To complete the cycle and swap out the new scene with the old one, developers have a choice to make. Many strategies exist for removing a scene -from view of the :ref:`Viewport `. The tradeoffs involve +from view of the `Viewport `. The tradeoffs involve balancing operation speed and memory consumption as well as balancing data access and integrity. 1. **We can delete the existing scene.** - :ref:`SceneTree.change_scene() ` and - :ref:`SceneTree.change_scene_to() ` + `SceneTree.change_scene() ` and + `SceneTree.change_scene_to() ` will delete the current scene immediately. Developers can also delete the main scene though. Assuming the root node's name is "Main", one could do ``get_node("/root/Main").free()`` to delete the whole scene. @@ -46,7 +46,7 @@ access and integrity. - Note: It can be useful to preserve the data in a soon-to-be-deleted scene by re-attaching one or more of its nodes to a different scene, - or even directly to the :ref:`SceneTree `. + or even directly to the `SceneTree `. - Processing stops. @@ -76,7 +76,7 @@ access and integrity. data. - Pro: Nodes are still members of groups (since groups belong to the - :ref:`SceneTree `). + `SceneTree `). - Con: The CPU's attention is now divided between both scenes. Too much load could result in low frame rates. One should be sure to test @@ -85,7 +85,7 @@ access and integrity. 3. **We can remove the existing scene from the tree.** Assign a variable to the existing scene's root node. Then use - :ref:`Node.remove_child(Node) ` to detach the entire + `Node.remove_child(Node) ` to detach the entire scene from the tree. - Memory still exists (similar pros/cons as with hiding it from view). @@ -99,7 +99,7 @@ access and integrity. - Con: Unlike with hiding it from view only, the data contained within the scene will become stale if it relies on delta time, input, groups, - or other data that is derived from :ref:`SceneTree ` + or other data that is derived from `SceneTree ` access. There are also cases where one may wish to have many scenes present at the same @@ -113,7 +113,7 @@ gdscript GDScript ``` Perhaps instead they wish to display multiple scenes at the same time using -:ref:`ViewportContainers `. This is optimal in +`ViewportContainers `. This is optimal in cases where the intent is to render different content in different parts of the screen. Minimaps and split-screen multiplayer are good examples. diff --git a/tutorials/scripting/creating_script_templates.rst b/tutorials/scripting/creating_script_templates.rst index 08defb0..11a6e29 100644 --- a/tutorials/scripting/creating_script_templates.rst +++ b/tutorials/scripting/creating_script_templates.rst @@ -36,7 +36,7 @@ Project-defined templates The default path to search for templates is the ``res://script_templates/`` directory. The path can be changed by configuring the ``editor/script_templates_search_path`` setting in the -:ref:`ProjectSettings `, both via code and the editor. +`ProjectSettings `, both via code and the editor. If no ``script_templates`` directory is found within a project, it is simply ignored. @@ -107,7 +107,7 @@ Base placeholders | ``%TS%`` | Indentation placeholder. The exact type and number of | | | whitespace characters used for indentation is determined by | | | the ``text_editor/indent/type`` and ``text_editor/indent/size``| -| | settings in the :ref:`EditorSettings ` | +| | settings in the `EditorSettings ` | | | respectively. | +-------------+----------------------------------------------------------------+ @@ -117,7 +117,7 @@ Type placeholders These are only relevant for GDScript with static typing. Whether these placeholders are actually replaced is determined by the ``text_editor/completion/add_type_hints`` setting in the -:ref:`EditorSettings `. +`EditorSettings `. +-------------------+--------------+ | Placeholder | Value | diff --git a/tutorials/scripting/cross_language_scripting.rst b/tutorials/scripting/cross_language_scripting.rst index 8a60cb3..dca903d 100644 --- a/tutorials/scripting/cross_language_scripting.rst +++ b/tutorials/scripting/cross_language_scripting.rst @@ -43,8 +43,8 @@ Instantiating C# nodes from GDScript ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Using C# from GDScript doesn't need much work. Once loaded -(see :ref:`doc_gdscript_classes_as_resources`), the script can be instantiated -with :ref:`new() `. +(see `doc_gdscript_classes_as_resources`), the script can be instantiated +with `new() `. :: @@ -68,15 +68,15 @@ Instantiating GDScript nodes from C# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From the C# side, everything work the same way. Once loaded, the GDScript can -be instantiated with :ref:`GDScript.New() `. +be instantiated with `GDScript.New() `. .. code-block:: csharp GDScript MyGDScript = (GDScript) GD.Load("res://path_to_gd_file.gd"); Object myGDScriptNode = (Godot.Object) MyGDScript.New(); // This is a Godot.Object -Here we are using an :ref:`class_Object`, but you can use type conversion like -explained in :ref:`doc_c_sharp_features_type_conversion_and_casting`. +Here we are using an `class_Object`, but you can use type conversion like +explained in `doc_c_sharp_features_type_conversion_and_casting`. Accessing fields ---------------- @@ -104,8 +104,8 @@ Accessing GDScript fields from C# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ As C# is statically typed, accessing GDScript from C# is a bit more -convoluted, you will have to use :ref:`Object.Get() ` -and :ref:`Object.Set() `. The first argument is the name of the field you want to access. +convoluted, you will have to use `Object.Get() ` +and `Object.Set() `. The first argument is the name of the field you want to access. .. code-block:: csharp @@ -118,7 +118,7 @@ and :ref:`Object.Set() `. The first argument is the nam Keep in mind that when setting a field value you should only use types the GDScript side knows about. -Essentially, you want to work with built-in types as described in :ref:`doc_gdscript` or classes extending :ref:`class_Object`. +Essentially, you want to work with built-in types as described in `doc_gdscript` or classes extending `class_Object`. Calling methods --------------- @@ -145,7 +145,7 @@ Calling GDScript methods from C# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To call GDScript methods from C# you'll need to use -:ref:`Object.Call() `. The first argument is the +`Object.Call() `. The first argument is the name of the method you want to call. The following arguments will be passed to said method. diff --git a/tutorials/scripting/debug/debugger_panel.rst b/tutorials/scripting/debug/debugger_panel.rst index f4c074c..dcef422 100644 --- a/tutorials/scripting/debug/debugger_panel.rst +++ b/tutorials/scripting/debug/debugger_panel.rst @@ -35,7 +35,7 @@ You can use the buttons in the top-right corner to: .. warning:: Breakpoints won't break on code if it's - :ref:`running in a thread `. + `running in a thread `. This is a current limitation of the GDScript debugger. Errors diff --git a/tutorials/scripting/debug/overview_of_debugging_tools.rst b/tutorials/scripting/debug/overview_of_debugging_tools.rst index 230ab57..8d3441f 100644 --- a/tutorials/scripting/debug/overview_of_debugging_tools.rst +++ b/tutorials/scripting/debug/overview_of_debugging_tools.rst @@ -18,7 +18,7 @@ Debugger Panel -------------- Many of Godot's debugging tools are part of the Debugger panel, which you can -find information about in :ref:`doc_debugger_panel`. +find information about in `doc_debugger_panel`. Debug menu options ------------------ @@ -93,7 +93,7 @@ debug your game with an external editor. .. warning:: Breakpoints won't break on code if it's - :ref:`running in a thread `. + `running in a thread `. This is a current limitation of the GDScript debugger. Debug project settings diff --git a/tutorials/scripting/evaluating_expressions.rst b/tutorials/scripting/evaluating_expressions.rst index b316cbf..4a75a1d 100644 --- a/tutorials/scripting/evaluating_expressions.rst +++ b/tutorials/scripting/evaluating_expressions.rst @@ -3,7 +3,7 @@ Evaluating expressions ====================== -Godot provides an :ref:`class_Expression` class you can use to evaluate expressions. +Godot provides an `class_Expression` class you can use to evaluate expressions. An expression can be: @@ -11,7 +11,7 @@ An expression can be: - A built-in method call like ``deg2rad(90)``. - A method call on an user-provided script like ``update_health()``, if ``base_instance`` is set to a value other than ``null`` when calling - :ref:`Expression.execute() `. + `Expression.execute() `. .. note:: @@ -95,7 +95,7 @@ Setting a base instance for the expression By default, an expression has a base instance of ``null``. This means the expression has no base instance associated to it. -When calling :ref:`Expression.execute() `, +When calling `Expression.execute() `, you can set the value of the ``base_instance`` parameter to a specific object instance such as ``self``, another script instance or even a singleton:: @@ -198,7 +198,7 @@ The output from the script will be:: Built-in functions ------------------ -Most methods available in the :ref:`class_@GDScript` scope are available in the +Most methods available in the `class_@GDScript` scope are available in the Expression class, even if no base instance is bound to the expression. The same parameters and return types are available. diff --git a/tutorials/scripting/filesystem.rst b/tutorials/scripting/filesystem.rst index a79adc0..c792ecf 100644 --- a/tutorials/scripting/filesystem.rst +++ b/tutorials/scripting/filesystem.rst @@ -77,7 +77,7 @@ 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`. +resolution is further explained in `doc_data_paths`. Host file system ---------------- diff --git a/tutorials/scripting/gdscript/gdscript_advanced.rst b/tutorials/scripting/gdscript/gdscript_advanced.rst index fb1be4d..6f327f3 100644 --- a/tutorials/scripting/gdscript/gdscript_advanced.rst +++ b/tutorials/scripting/gdscript/gdscript_advanced.rst @@ -166,9 +166,9 @@ too. Some Examples: In GDScript, only base types (int, float, String and PoolArray types) are passed by value to functions (value is copied). Everything else (instances, Arrays, Dictionaries, etc) is passed as reference. Classes -that inherit :ref:`class_Reference` (the default if nothing is specified) +that inherit `class_Reference` (the default if nothing is specified) will be freed when not used, but manual memory management is allowed too -if inheriting manually from :ref:`class_Object`. +if inheriting manually from `class_Object`. .. note:: diff --git a/tutorials/scripting/gdscript/gdscript_basics.rst b/tutorials/scripting/gdscript/gdscript_basics.rst index c5a3930..0e823c9 100644 --- a/tutorials/scripting/gdscript/gdscript_basics.rst +++ b/tutorials/scripting/gdscript/gdscript_basics.rst @@ -19,7 +19,7 @@ History .. note:: Documentation about GDScript's history has been moved to the - :ref:`Frequently Asked Questions `. + `Frequently Asked Questions `. Example of GDScript ~~~~~~~~~~~~~~~~~~~ @@ -109,7 +109,7 @@ here's a simple example of how GDScript looks. If you have previous experience with statically typed languages such as C, C++, or C# but never used a dynamically typed one before, it is advised you -read this tutorial: :ref:`doc_gdscript_more_efficiently`. +read this tutorial: `doc_gdscript_more_efficiently`. Language -------- @@ -200,17 +200,17 @@ in case you want to take a look under the hood. +------------+---------------------------------------------------------------------------------------------------------------+ | assert | Asserts a condition, logs error on failure. Ignored in non-debug builds. See `Assert keyword`_. | +------------+---------------------------------------------------------------------------------------------------------------+ -| remote | Networking RPC annotation. See :ref:`high-level multiplayer docs `. | +| remote | Networking RPC annotation. See `high-level multiplayer docs `. | +------------+---------------------------------------------------------------------------------------------------------------+ -| master | Networking RPC annotation. See :ref:`high-level multiplayer docs `. | +| master | Networking RPC annotation. See `high-level multiplayer docs `. | +------------+---------------------------------------------------------------------------------------------------------------+ -| puppet | Networking RPC annotation. See :ref:`high-level multiplayer docs `. | +| puppet | Networking RPC annotation. See `high-level multiplayer docs `. | +------------+---------------------------------------------------------------------------------------------------------------+ -| remotesync | Networking RPC annotation. See :ref:`high-level multiplayer docs `. | +| remotesync | Networking RPC annotation. See `high-level multiplayer docs `. | +------------+---------------------------------------------------------------------------------------------------------------+ -| mastersync | Networking RPC annotation. See :ref:`high-level multiplayer docs `. | +| mastersync | Networking RPC annotation. See `high-level multiplayer docs `. | +------------+---------------------------------------------------------------------------------------------------------------+ -| puppetsync | Networking RPC annotation. See :ref:`high-level multiplayer docs `. | +| puppetsync | Networking RPC annotation. See `high-level multiplayer docs `. | +------------+---------------------------------------------------------------------------------------------------------------+ | PI | PI constant. | +------------+---------------------------------------------------------------------------------------------------------------+ @@ -303,7 +303,7 @@ Literals +--------------------------+----------------------------------------+ | ``"""Hello"""`` | Multiline string | +--------------------------+----------------------------------------+ -| ``@"Node/Label"`` | :ref:`class_NodePath` or StringName | +| ``@"Node/Label"`` | `class_NodePath` or StringName | +--------------------------+----------------------------------------+ | ``$NodePath`` | Shorthand for ``get_node("NodePath")`` | +--------------------------+----------------------------------------+ @@ -348,18 +348,18 @@ null ``null`` is an empty data type that contains no information and can not be assigned any other value. -:ref:`bool ` +`bool ` ^^^^^^^^^^^^^^^^^^^^^^^^ Short for "boolean", it can only contain ``true`` or ``false``. -:ref:`int ` +`int ` ^^^^^^^^^^^^^^^^^^^^^^ Short for "integer", it stores whole numbers (positive and negative). It is stored as a 64-bit value, equivalent to "int64_t" in C++. -:ref:`float ` +`float ` ^^^^^^^^^^^^^^^^^^^^^^^^^^ Stores real numbers, including decimals, using floating-point values. @@ -367,7 +367,7 @@ It is stored as a 64-bit value, equivalent to "double" in C++. Note: Currently, data structures such as Vector2, Vector3, and PoolRealArray store 32-bit single-precision "float" values. -:ref:`String ` +`String ` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A sequence of characters in `Unicode format `_. @@ -400,61 +400,61 @@ Strings can contain the following escape sequences: | | (hexadecimal, case-insensitive) | +---------------------+---------------------------------+ -GDScript also supports :ref:`doc_gdscript_printf`. +GDScript also supports `doc_gdscript_printf`. Vector built-in types ~~~~~~~~~~~~~~~~~~~~~ -:ref:`Vector2 ` +`Vector2 ` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2D vector type containing ``x`` and ``y`` fields. Can also be accessed as an array. -:ref:`Rect2 ` +`Rect2 ` ^^^^^^^^^^^^^^^^^^^^^^^^^^ 2D Rectangle type containing two vectors fields: ``position`` and ``size``. Also contains an ``end`` field which is ``position + size``. -:ref:`Vector3 ` +`Vector3 ` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3D vector type containing ``x``, ``y`` and ``z`` fields. This can also be accessed as an array. -:ref:`Transform2D ` +`Transform2D ` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3×2 matrix used for 2D transforms. -:ref:`Plane ` +`Plane ` ^^^^^^^^^^^^^^^^^^^^^^^^^^ 3D Plane type in normalized form that contains a ``normal`` vector field and a ``d`` scalar distance. -:ref:`Quat ` +`Quat ` ^^^^^^^^^^^^^^^^^^^^^^^^ Quaternion is a datatype used for representing a 3D rotation. It's useful for interpolating rotations. -:ref:`AABB ` +`AABB ` ^^^^^^^^^^^^^^^^^^^^^^^^ Axis-aligned bounding box (or 3D box) contains 2 vectors fields: ``position`` and ``size``. Also contains an ``end`` field which is ``position + size``. -:ref:`Basis ` +`Basis ` ^^^^^^^^^^^^^^^^^^^^^^^^^^ 3x3 matrix used for 3D rotation and scale. It contains 3 vector fields (``x``, ``y`` and ``z``) and can also be accessed as an array of 3D vectors. -:ref:`Transform ` +`Transform ` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3D Transform contains a Basis field ``basis`` and a Vector3 field @@ -463,24 +463,24 @@ vectors. Engine built-in types ~~~~~~~~~~~~~~~~~~~~~ -:ref:`Color ` +`Color ` ^^^^^^^^^^^^^^^^^^^^^^^^^^ Color data type contains ``r``, ``g``, ``b``, and ``a`` fields. It can also be accessed as ``h``, ``s``, and ``v`` for hue/saturation/value. -:ref:`NodePath ` +`NodePath ` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Compiled path to a node used mainly in the scene system. It can be easily assigned to, and from, a String. -:ref:`RID ` +`RID ` ^^^^^^^^^^^^^^^^^^^^^^ Resource ID (RID). Servers use generic RIDs to reference opaque data. -:ref:`Object ` +`Object ` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Base class for anything that is not a built-in type. @@ -488,7 +488,7 @@ Base class for anything that is not a built-in type. Container built-in types ~~~~~~~~~~~~~~~~~~~~~~~~ -:ref:`Array ` +`Array ` ^^^^^^^^^^^^^^^^^^^^^^^^^^ Generic sequence of arbitrary object types, including other arrays or dictionaries (see below). @@ -512,15 +512,15 @@ arrays are available. These only accept a single data type. They avoid memory fragmentation and use less memory, but are atomic and tend to run slower than generic arrays. They are therefore only recommended to use for large data sets: -- :ref:`PoolByteArray `: An array of bytes (integers from 0 to 255). -- :ref:`PoolIntArray `: An array of integers. -- :ref:`PoolRealArray `: An array of floats. -- :ref:`PoolStringArray `: An array of strings. -- :ref:`PoolVector2Array `: An array of :ref:`Vector2 ` objects. -- :ref:`PoolVector3Array `: An array of :ref:`Vector3 ` objects. -- :ref:`PoolColorArray `: An array of :ref:`Color ` objects. +- `PoolByteArray `: An array of bytes (integers from 0 to 255). +- `PoolIntArray `: An array of integers. +- `PoolRealArray `: An array of floats. +- `PoolStringArray `: An array of strings. +- `PoolVector2Array `: An array of `Vector2 ` objects. +- `PoolVector3Array `: An array of `Vector3 ` objects. +- `PoolColorArray `: An array of `Color ` objects. -:ref:`Dictionary ` +`Dictionary ` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Associative container which contains values referenced by unique keys. @@ -567,10 +567,10 @@ assign to it:: .. note:: The bracket syntax can be used to access properties of any - :ref:`class_Object`, not just Dictionaries. Keep in mind it will cause a + `class_Object`, not just Dictionaries. Keep in mind it will cause a script error when attempting to index a non-existing property. To avoid - this, use the :ref:`Object.get() ` and - :ref:`Object.set() ` methods instead. + this, use the `Object.get() ` and + `Object.set() ` methods instead. Data ---- @@ -1099,7 +1099,7 @@ class will then appear with its new icon in the editor:: If the script is located in the ``res://addons/`` directory, ``class_name`` will only cause the node to show up in the **Create New Node** dialog if - the script is part of an *enabled* editor plugin. See :ref:`doc_making_plugins` + the script is part of an *enabled* editor plugin. See `doc_making_plugins` for more information. Here's a class file example: @@ -1270,7 +1270,7 @@ function. Classes as resources ^^^^^^^^^^^^^^^^^^^^ -Classes stored as files are treated as :ref:`resources `. They +Classes stored as files are treated as `resources `. They must be loaded from disk to access them in other classes. This is done using either the ``load`` or ``preload`` functions (see below). Instancing of a loaded class resource is done by calling the ``new`` function on the class object:: @@ -1291,7 +1291,7 @@ Exports .. note:: - Documentation about exports has been moved to :ref:`doc_gdscript_exports`. + Documentation about exports has been moved to `doc_gdscript_exports`. Setters/getters ~~~~~~~~~~~~~~~ @@ -1329,7 +1329,7 @@ Either of the *setter* or *getter* functions can be omitted:: # Only a getter (note the comma). var my_var = 5 setget ,my_var_get -Setters and getters are useful when :ref:`exporting variables ` +Setters and getters are useful when `exporting variables ` to the editor in tool scripts or plugins, for validating input. As said, *local* access will *not* trigger the setter and getter. Here is an @@ -1365,7 +1365,7 @@ placed at the top of the file:: print("Hello") -See :ref:`doc_running_code_in_the_editor` for more information. +See `doc_running_code_in_the_editor` for more information. .. warning:: Be cautious when freeing nodes with ``queue_free()`` or ``free()`` in a tool script (especially the script's owner itself). As tool @@ -1377,12 +1377,12 @@ See :ref:`doc_running_code_in_the_editor` for more information. Memory management ~~~~~~~~~~~~~~~~~ -If a class inherits from :ref:`class_Reference`, then instances will be +If a class inherits from `class_Reference`, then instances will be freed when no longer in use. No garbage collector exists, just reference counting. By default, all classes that don't define inheritance extend **Reference**. If this is not desired, then a class -must inherit :ref:`class_Object` manually and must call ``instance.free()``. To -avoid reference cycles that can't be freed, a :ref:`class_WeakRef` function is +must inherit `class_Object` manually and must call ``instance.free()``. To +avoid reference cycles that can't be freed, a `class_WeakRef` function is provided for creating weak references. Here is an example: :: @@ -1429,7 +1429,7 @@ to. To create custom signals for a class, use the ``signal`` keyword. Game Programming Patterns ebook. You can connect these signals to methods the same way you connect built-in -signals of nodes like :ref:`class_Button` or :ref:`class_RigidBody`. +signals of nodes like `class_Button` or `class_RigidBody`. In the example below, we connect the ``health_depleted`` signal from a ``Character`` node to a ``Game`` node. When the ``Character`` node emits the @@ -1452,9 +1452,9 @@ to react to health changes with an animation, but we want to keep the user interface separate from the player in our scene tree. In our ``Character.gd`` script, we define a ``health_changed`` signal and emit -it with :ref:`Object.emit_signal() `, and from +it with `Object.emit_signal() `, and from a ``Game`` node higher up our scene tree, we connect it to the ``Lifebar`` using -the :ref:`Object.connect() ` method:: +the `Object.connect() ` method:: # Character.gd @@ -1563,7 +1563,7 @@ Coroutines with yield ~~~~~~~~~~~~~~~~~~~~~ GDScript offers support for `coroutines `_ -via the :ref:`yield` built-in function. Calling ``yield()`` will +via the `yield` built-in function. Calling ``yield()`` will immediately return from the current function, with the current frozen state of the same function as the return value. Calling ``resume()`` on this resulting object will continue execution and return whatever the diff --git a/tutorials/scripting/gdscript/gdscript_exports.rst b/tutorials/scripting/gdscript/gdscript_exports.rst index be2f58e..4bbf7f9 100644 --- a/tutorials/scripting/gdscript/gdscript_exports.rst +++ b/tutorials/scripting/gdscript/gdscript_exports.rst @@ -7,7 +7,7 @@ Introduction to exports ----------------------- In Godot, class members can be exported. This means their value gets saved along -with the resource (such as the :ref:`scene `) they're +with the resource (such as the `scene `) they're attached to. They will also be available for editing in the property editor. Exporting is done by using the ``export`` keyword:: @@ -138,7 +138,7 @@ Examples It must be noted that even if the script is not being run while in the editor, the exported properties are still editable. This can be used -in conjunction with a :ref:`script in "tool" mode `. +in conjunction with a `script in "tool" mode `. Exporting bit flags ------------------- @@ -211,9 +211,9 @@ Setting exported variables from a tool script --------------------------------------------- When changing an exported variable's value from a script in -:ref:`doc_gdscript_tool_mode`, the value in the inspector won't be updated +`doc_gdscript_tool_mode`, the value in the inspector won't be updated automatically. To update it, call -:ref:`property_list_changed_notify() ` +`property_list_changed_notify() ` after setting the exported variable's value. Advanced exports @@ -225,13 +225,13 @@ common exporting features which can be implemented with a low-level API. Before reading further, you should get familiar with the way properties are handled and how they can be customized with -:ref:`_set() `, -:ref:`_get() `, and -:ref:`_get_property_list() ` methods as -described in :ref:`doc_accessing_data_or_logic_from_object`. +`_set() `, +`_get() `, and +`_get_property_list() ` methods as +described in `doc_accessing_data_or_logic_from_object`. .. seealso:: For binding properties using the above methods in C++, see - :ref:`doc_binding_properties_using_set_get_property_list`. + `doc_binding_properties_using_set_get_property_list`. .. warning:: The script must operate in the ``tool`` mode so the above methods can work from within the editor. @@ -269,8 +269,8 @@ Attaching variables to properties To attach variables to properties (allowing the value of the property to be used in scripts), you need to create a variable with the exact same name as the property or else you may need to override the -:ref:`_set() ` and -:ref:`_get() ` methods. Attaching +`_set() ` and +`_get() ` methods. Attaching a variable to to a property also gives you the ability to give it a default state. :: diff --git a/tutorials/scripting/gdscript/gdscript_styleguide.rst b/tutorials/scripting/gdscript/gdscript_styleguide.rst index 7b37f12..f9d829b 100644 --- a/tutorials/scripting/gdscript/gdscript_styleguide.rst +++ b/tutorials/scripting/gdscript/gdscript_styleguide.rst @@ -615,7 +615,7 @@ Code order ---------- This first section focuses on code order. For formatting, see -:ref:`formatting`. For naming conventions, see :ref:`naming_conventions`. +`formatting`. For naming conventions, see `naming_conventions`. We suggest to organize GDScript code this way: @@ -661,7 +661,7 @@ first line of the script. Follow with the `class_name` if necessary. You can turn a GDScript file into a global type in your project using this feature. For more information, see -:ref:`doc_gdscript`. +`doc_gdscript`. Then, add the `extends` keyword if the class extends a built-in type. @@ -784,7 +784,7 @@ in that order. Static typing ------------- -Since Godot 3.1, GDScript supports :ref:`optional static typing`. +Since Godot 3.1, GDScript supports `optional static typing`. Declared types ~~~~~~~~~~~~~~ @@ -831,7 +831,7 @@ that type will be used to infer the type of the var. onready var health_bar := get_node("UI/LifeBar") as ProgressBar # health_bar will be typed as ProgressBar -This option is also considered more :ref:`type-safe` than the first. +This option is also considered more `type-safe` than the first. **Bad**: diff --git a/tutorials/scripting/gdscript/index.rst b/tutorials/scripting/gdscript/index.rst index 16ee4e6..612f347 100644 --- a/tutorials/scripting/gdscript/index.rst +++ b/tutorials/scripting/gdscript/index.rst @@ -15,5 +15,5 @@ GDScript .. seealso:: - See :ref:`doc_gdscript_grammar` if you are interested in writing a third-party + See `doc_gdscript_grammar` if you are interested in writing a third-party tool that interacts with GDScript, such as a linter or formatter. diff --git a/tutorials/scripting/gdscript/static_typing.rst b/tutorials/scripting/gdscript/static_typing.rst index 66ce19c..79031bf 100644 --- a/tutorials/scripting/gdscript/static_typing.rst +++ b/tutorials/scripting/gdscript/static_typing.rst @@ -104,10 +104,10 @@ type: Currently you can use three types of… types: -1. :ref:`Built-in ` +1. `Built-in ` 2. Core classes and nodes (``Object``, ``Node``, ``Area2D``, ``Camera2D``, etc.) -3. Your own custom classes. Look at the new :ref:`class_name ` +3. Your own custom classes. Look at the new `class_name ` feature to register types in the editor. .. note:: @@ -323,7 +323,7 @@ Warning system .. note:: Documentation about the GDScript warning system has been moved to - :ref:`doc_gdscript_warning_system`. + `doc_gdscript_warning_system`. Cases where you can't specify types ----------------------------------- diff --git a/tutorials/scripting/gdscript/warning_system.rst b/tutorials/scripting/gdscript/warning_system.rst index 04ec943..b650e19 100644 --- a/tutorials/scripting/gdscript/warning_system.rst +++ b/tutorials/scripting/gdscript/warning_system.rst @@ -3,7 +3,7 @@ GDScript warning system ======================= -The GDScript warning system complements :ref:`static typing ` +The GDScript warning system complements `static typing ` (but it can work without static typing too). It's here to help you avoid mistakes that are hard to spot during development, and that may lead to runtime errors. diff --git a/tutorials/scripting/groups.rst b/tutorials/scripting/groups.rst index a53f6db..dcb0a3d 100644 --- a/tutorials/scripting/groups.rst +++ b/tutorials/scripting/groups.rst @@ -22,8 +22,8 @@ removed by removing all nodes from a given group. There are two ways to add/remove nodes to groups: - During design, by using the Node dock in the editor. -- During execution, by calling :ref:`Node.add_to_group() ` - or :ref:`Node.remove_from_group() `. +- During execution, by calling `Node.add_to_group() ` + or `Node.remove_from_group() `. Using the Node dock @@ -98,7 +98,7 @@ The above code calls the function ``enter_alert_mode`` on every member of the group ``guards``. To get the full list of nodes in the ``guards`` group as an array, you can call -:ref:`SceneTree.get_nodes_in_group() +`SceneTree.get_nodes_in_group() `: gdscript GDScript @@ -107,7 +107,7 @@ gdscript GDScript var guards = get_tree().get_nodes_in_group("guards") ``` -The :ref:`SceneTree ` class provides many more useful methods +The `SceneTree ` class provides many more useful methods to interact with scenes, their node hierarchy, and groups. It allows you to switch scenes easily or reload them, quit the game or pause and unpause it. It also provides useful signals. diff --git a/tutorials/scripting/idle_and_physics_processing.rst b/tutorials/scripting/idle_and_physics_processing.rst index a1f442e..23f2c5c 100644 --- a/tutorials/scripting/idle_and_physics_processing.rst +++ b/tutorials/scripting/idle_and_physics_processing.rst @@ -5,8 +5,8 @@ Idle and Physics Processing Games run in a loop. Each frame, you need to update the state of your game world before drawing it on screen. Godot provides two virtual methods in the Node -class to do so: :ref:`Node._process() ` and -:ref:`Node._physics_process() `. If you +class to do so: `Node._process() ` and +`Node._physics_process() `. If you define either or both in a script, the engine will call them automatically. There are two types of processing available to you: @@ -19,7 +19,7 @@ There are two types of processing available to you: engine, like moving a body that collides with the environment. You can activate idle processing by defining the ``_process()`` method in a -script. You can turn it off and back on by calling :ref:`Node.set_process() +script. You can turn it off and back on by calling `Node.set_process() `. The engine calls this method every time it draws a frame: diff --git a/tutorials/scripting/index.rst b/tutorials/scripting/index.rst index 3e8aece..e67721c 100644 --- a/tutorials/scripting/index.rst +++ b/tutorials/scripting/index.rst @@ -6,7 +6,7 @@ in Godot. Here, you will find information that is not already covered in more specific sections. For instance, to learn about inputs, we recommend you to read -:ref:`Inputs `. +`Inputs `. Programming languages --------------------- diff --git a/tutorials/scripting/instancing_with_signals.rst b/tutorials/scripting/instancing_with_signals.rst index f0e967d..0ce909a 100644 --- a/tutorials/scripting/instancing_with_signals.rst +++ b/tutorials/scripting/instancing_with_signals.rst @@ -20,7 +20,7 @@ Shooting example Consider a player character that can rotate and shoot towards the mouse. Every time the mouse button is clicked, we create an instance of the bullet at the -player's location. See :ref:`doc_instancing` for details. +player's location. See `doc_instancing` for details. We'll use an ``Area2D`` for the bullet, which moves in a straight line at a given velocity: diff --git a/tutorials/scripting/nodes_and_scene_instances.rst b/tutorials/scripting/nodes_and_scene_instances.rst index fee6487..cbb6f29 100644 --- a/tutorials/scripting/nodes_and_scene_instances.rst +++ b/tutorials/scripting/nodes_and_scene_instances.rst @@ -9,7 +9,7 @@ instantiate scenes from code. Getting nodes ------------- -You can get a reference to a node by calling the :ref:`Node.get_node() +You can get a reference to a node by calling the `Node.get_node() ` method. For this to work, the child node must be present in the scene tree. Getting it in the parent node's ``_ready()`` function guarantees that. @@ -146,7 +146,7 @@ like. This operation is called instancing, and doing it from code happens in two steps: 1. Loading the scene from the hard drive. -2. Creating an instance of the loaded :ref:`PackedScene ` +2. Creating an instance of the loaded `PackedScene ` resource. gdscript GDScript @@ -166,7 +166,7 @@ gdscript GDScript ``` At that point, ``scene`` is a packed scene resource, not a node. To create the -actual node, you need to call :ref:`PackedScene.instance() +actual node, you need to call `PackedScene.instance() `. It returns a tree of nodes that you can as a child of your current node. diff --git a/tutorials/scripting/overridable_functions.rst b/tutorials/scripting/overridable_functions.rst index 3a7d68d..af4f3f7 100644 --- a/tutorials/scripting/overridable_functions.rst +++ b/tutorials/scripting/overridable_functions.rst @@ -10,7 +10,7 @@ This document presents the ones you'll use most often. .. seealso:: Under the hood, these functions rely on Godot's low-level notifications system. To learn more about it, see - :ref:`doc_godot_notifications`. + `doc_godot_notifications`. Two functions allow you to initialize and get nodes, besides the class's constructor: ``_enter_tree()`` and ``_ready()``. @@ -25,10 +25,10 @@ once in a node's lifetime, after ``_enter_tree()``. ``_ready()`` ensures that al have entered the scene tree first, so you can safely call ``get_node()`` on it. .. seealso:: To learn more about getting node references, read - :ref:`doc_nodes_and_scene_instances`. + `doc_nodes_and_scene_instances`. Another related callback is ``_exit_tree()``, which the engine calls every time -a node exits the scene tree. This can be when you call :ref:`Node.remove_child() +a node exits the scene tree. This can be when you call `Node.remove_child() ` or when you free a node. gdscript GDScript @@ -51,7 +51,7 @@ gdscript GDScript The two virtual methods ``_process()`` and ``_physics_process()`` allow you to update the node, every frame and every physics frame respectively. For more information, read the dedicated documentation: -:ref:`doc_idle_and_physics_processing`. +`doc_idle_and_physics_processing`. gdscript GDScript @@ -66,15 +66,15 @@ gdscript GDScript ``` Two more essential built-in node callback functions are -:ref:`Node._unhandled_input() ` and -:ref:`Node._input() `, which you use to both receive +`Node._unhandled_input() ` and +`Node._input() `, which you use to both receive and process individual input events. The ``_unhandled_input()`` method receives every key press, mouse click, etc. that have not been handled already in an ``_input()`` callback or in a user interface component. You want to use it for gameplay input in general. The ``_input()`` callback allows you to intercept and process input events before ``_unhandled_input()`` gets them. -To learn more about inputs in Godot, see the :ref:`Input section `. +To learn more about inputs in Godot, see the `Input section `. gdscript GDScript @@ -90,8 +90,8 @@ gdscript GDScript ``` There are some more overridable functions like -:ref:`Node._get_configuration_warning() +`Node._get_configuration_warning() `. Specialized node types provide -more callbacks like :ref:`CanvasItem._draw() ` to -draw programmatically or :ref:`Control._gui_input() +more callbacks like `CanvasItem._draw() ` to +draw programmatically or `Control._gui_input() ` to handle clicks and input on UI elements. diff --git a/tutorials/scripting/pausing_games.rst b/tutorials/scripting/pausing_games.rst index a028fc3..0297190 100644 --- a/tutorials/scripting/pausing_games.rst +++ b/tutorials/scripting/pausing_games.rst @@ -16,7 +16,7 @@ How pausing works ----------------- To pause the game the pause state must be set. This is done by assigning -``true`` to the :ref:`SceneTree.paused ` property: +``true`` to the `SceneTree.paused ` property: gdscript GDScript @@ -35,7 +35,7 @@ Process Modes ------------- Each node in Godot has a "Pause Mode" that defines when it processes. It can -be found and changed under a node's :ref:`Node ` properties in the inspector. +be found and changed under a node's `Node ` properties in the inspector. .. image:: img/pausemode.png diff --git a/tutorials/scripting/resources.rst b/tutorials/scripting/resources.rst index 230d477..d4fd4e5 100644 --- a/tutorials/scripting/resources.rst +++ b/tutorials/scripting/resources.rst @@ -6,11 +6,11 @@ Resources Nodes and resources ------------------- -Up to this tutorial, we focused on the :ref:`Node ` +Up to this tutorial, we focused on the `Node ` class in Godot as that's the one you use to code behavior and most of the engine's features rely on it. There is another datatype that is just as important: -:ref:`Resource `. +`Resource `. *Nodes* give you functionality: they draw sprites, 3D models, simulate physics, arrange user interfaces, etc. **Resources** are **data containers**. They don't @@ -18,9 +18,9 @@ do anything on their own: instead, nodes use the data contained in resources. Anything Godot saves or loads from disk is a resource. Be it a scene (a ``.tscn`` or an ``.scn`` file), an image, a script... Here are some ``Resource`` examples: -:ref:`Texture `, :ref:`Script `, :ref:`Mesh -`, :ref:`Animation `, :ref:`AudioStream -`, :ref:`Font `, :ref:`Translation +`Texture `, `Script `, `Mesh +`, `Animation `, `AudioStream +`, `Font `, `Translation `. When the engine loads a resource from disk, **it only loads it once**. If a copy @@ -43,8 +43,8 @@ There are two ways to save resources. They can be: 1. **External** to a scene, saved on the disk as individual files. 2. **Built-in**, saved inside the ``.tscn`` or the ``.scn`` file they're attached to. -To be more specific, here's a :ref:`Texture ` -in a :ref:`Sprite ` node: +To be more specific, here's a `Texture ` +in a `Sprite ` node: .. image:: img/spriteprop.png @@ -95,11 +95,11 @@ Loading scenes -------------- Scenes are also resources, but there is a catch. Scenes saved to disk are -resources of type :ref:`PackedScene `. The +resources of type `PackedScene `. The scene is packed inside a resource. To get an instance of the scene, you have to use the -:ref:`PackedScene.instance() ` method. +`PackedScene.instance() ` method. gdscript GDScript @@ -113,7 +113,7 @@ This method creates the nodes in the scene's hierarchy, configures them, and returns the root node of the scene. You can then add it as a child of any other node. -The approach has several advantages. As the :ref:`PackedScene.instance() +The approach has several advantages. As the `PackedScene.instance() ` function is fast, you can create new enemies, bullets, effects, etc. without having to load them again from disk each time. Remember that, as always, images, meshes, etc. are all shared between the @@ -136,10 +136,10 @@ memory management from the Reference type. This comes with many distinct advantages over alternative data structures, such as JSON, CSV, or custom TXT files. Users can only import these -assets as a :ref:`Dictionary ` (JSON) or as a -:ref:`File ` to parse. What sets Resources apart is their -inheritance of :ref:`Object `, :ref:`Reference `, -and :ref:`Resource ` features: +assets as a `Dictionary ` (JSON) or as a +`File ` to parse. What sets Resources apart is their +inheritance of `Object `, `Reference `, +and `Resource ` features: - They can define constants, so constants from other data fields or objects are not needed. @@ -169,7 +169,7 @@ those values and saves the resource, the Inspector serializes the custom propert too! To save a resource from the Inspector, click the Inspector's tools menu (top right), and select "Save" or "Save As...". -If the script's language supports :ref:`script classes `, +If the script's language supports `script classes `, then it streamlines the process. Defining a name for your script alone will add it to the Inspector's creation dialog. This will auto-add your script to the Resource object you create. @@ -209,7 +209,7 @@ gdscript GDScript Resource scripts are similar to Unity's ScriptableObjects. The Inspector provides built-in support for custom resources. If desired though, users can even design their own Control-based tool scripts and combine them - with an :ref:`EditorPlugin ` to create custom + with an `EditorPlugin ` to create custom visualizations and editors for their data. Unreal Engine 4's DataTables and CurveTables are also easy to recreate with @@ -257,7 +257,7 @@ gdscript GDScript to the Inspector when you open these types of Resources. CurveTables are the same thing, except mapped to an Array of float values - or a :ref:`Curve `/:ref:`Curve2D ` resource object. + or a `Curve `/`Curve2D ` resource object. .. warning:: diff --git a/tutorials/scripting/scene_tree.rst b/tutorials/scripting/scene_tree.rst index 45866aa..4dd950e 100644 --- a/tutorials/scripting/scene_tree.rst +++ b/tutorials/scripting/scene_tree.rst @@ -14,12 +14,12 @@ MainLoop -------- The way Godot works internally is as follows. There is the -:ref:`OS ` class, +`OS ` class, which is the only instance that runs at the beginning. Afterwards, all drivers, servers, scripting languages, scene system, etc are loaded. -When initialization is complete, :ref:`OS ` needs to be -supplied a :ref:`MainLoop ` +When initialization is complete, `OS ` needs to be +supplied a `MainLoop ` to run. Up to this point, all this is internals working (you can check main/main.cpp file in the source code if you are ever interested to see how this works internally). @@ -35,18 +35,18 @@ SceneTree One of the ways to explain how Godot works is that it's a high level game engine over a low level middleware. -The scene system is the game engine, while the :ref:`OS ` +The scene system is the game engine, while the `OS ` and servers are the low level API. The scene system provides its own main loop to OS, -:ref:`SceneTree `. +`SceneTree `. This is automatically instanced and set when running a scene, no need to do any extra work. It's important to know that this class exists because it has a few important uses: -- It contains the root :ref:`Viewport `, to which a +- It contains the root `Viewport `, to which a scene is added as a child when it's first opened to become part of the *Scene Tree* (more on that next). - It contains information about the groups and has the means to call all @@ -55,14 +55,14 @@ important uses: mode or quitting the process. When a node is part of the Scene Tree, the -:ref:`SceneTree ` +`SceneTree ` singleton can be obtained by calling -:ref:`Node.get_tree() `. +`Node.get_tree() `. Root viewport ------------- -The root :ref:`Viewport ` +The root `Viewport ` is always at the top of the scene. From a node, it can be obtained in two different ways: @@ -74,7 +74,7 @@ gdscript GDScript ``` This node contains the main viewport. Anything that is a child of a -:ref:`Viewport ` +`Viewport ` is drawn inside of it by default, so it makes sense that the top of all nodes is always a node of this type otherwise nothing would be seen. @@ -130,7 +130,7 @@ Changing current scene After a scene is loaded, it is often desired to change this scene for another one. The simple way to do this is to use the -:ref:`SceneTree.change_scene() ` +`SceneTree.change_scene() ` function: gdscript GDScript @@ -141,9 +141,9 @@ gdscript GDScript ``` Rather than using file paths, one can also use ready-made -:ref:`PackedScene ` resources using the equivalent +`PackedScene ` resources using the equivalent function -:ref:`SceneTree.change_scene_to(PackedScene scene) `: +`SceneTree.change_scene_to(PackedScene scene) `: gdscript GDScript @@ -159,4 +159,4 @@ that the game will stall until the new scene is loaded and running. At some point in the development of your game, it may be preferable to create proper loading screens with progress bar, animated indicators or thread (background) loading. This must be done manually using autoloads (see next chapter) -and :ref:`doc_background_loading`. +and `doc_background_loading`. diff --git a/tutorials/scripting/singletons_autoload.rst b/tutorials/scripting/singletons_autoload.rst index 144c21d..f802644 100644 --- a/tutorials/scripting/singletons_autoload.rst +++ b/tutorials/scripting/singletons_autoload.rst @@ -43,18 +43,18 @@ Autoloading nodes and scripts can give us these characteristics. .. tip:: If you're creating an autoload as part of an editor plugin, consider - :ref:`registering it automatically in the Project Settings ` + `registering it automatically in the Project Settings ` when the plugin is enabled. AutoLoad -------- You can create an AutoLoad to load a scene or a script that inherits from -:ref:`class_Node`. +`class_Node`. .. note:: - When autoloading a script, a :ref:`class_Node` will be created and the script will be + When autoloading a script, a `class_Node` will be created and the script will be attached to it. This node will be added to the root viewport before any other scenes are loaded. @@ -107,8 +107,8 @@ Custom scene switcher This tutorial will demonstrate building a scene switcher using autoloads. For basic scene switching, you can use the -:ref:`SceneTree.change_scene() ` -method (see :ref:`doc_scene_tree` for details). However, if you need more +`SceneTree.change_scene() ` +method (see `doc_scene_tree` for details). However, if you need more complex behavior when changing scenes, this method provides more functionality. To begin, download the template from here: @@ -189,7 +189,7 @@ gdscript GDScript get_tree().current_scene = current_scene ``` -Using :ref:`Object.call_deferred() `, +Using `Object.call_deferred() `, the second function will only run once all code from the current scene has completed. Thus, the current scene will not be removed while it is still being used (i.e. its code is still running). @@ -223,7 +223,7 @@ the button. When scenes are small, the transition is instantaneous. However, if your scenes are more complex, they may take a noticeable amount of time to appear. - To learn how to handle this, see the next tutorial: :ref:`doc_background_loading`. + To learn how to handle this, see the next tutorial: `doc_background_loading`. Alternatively, if the loading time is relatively short (less than 3 seconds or so), you can display a "loading plaque" by showing some kind of 2D element just before diff --git a/tutorials/shaders/advanced_postprocessing.rst b/tutorials/shaders/advanced_postprocessing.rst index aab2d6d..ecaa494 100644 --- a/tutorials/shaders/advanced_postprocessing.rst +++ b/tutorials/shaders/advanced_postprocessing.rst @@ -9,10 +9,10 @@ Introduction This tutorial describes an advanced method for post-processing in Godot. In particular, it will explain how to write a post-processing shader that uses the depth buffer. You should already be familiar with post-processing -generally and, in particular, with the methods outlined in the :ref:`custom post-processing tutorial `. +generally and, in particular, with the methods outlined in the `custom post-processing tutorial `. -In the previous post-processing tutorial, we rendered the scene to a :ref:`Viewport ` -and then rendered the Viewport in a :ref:`ViewportContainer ` +In the previous post-processing tutorial, we rendered the scene to a `Viewport ` +and then rendered the Viewport in a `ViewportContainer ` to the main scene. One limitation of this method is that we could not access the depth buffer because the depth buffer is only available in spatial shaders and Viewports do not maintain depth information. @@ -20,15 +20,15 @@ Viewports do not maintain depth information. Full screen quad ---------------- -In the :ref:`custom post-processing tutorial `, we +In the `custom post-processing tutorial `, we covered how to use a Viewport to make custom post-processing effects. There are two main drawbacks of using a Viewport: 1. The depth buffer cannot be accessed 2. The effect of the post-processing shader is not visible in the editor -To get around the limitation on using the depth buffer, use a :ref:`MeshInstance ` -with a :ref:`QuadMesh ` primitive. This allows us to use a spatial +To get around the limitation on using the depth buffer, use a `MeshInstance ` +with a `QuadMesh ` primitive. This allows us to use a spatial shader and to access the depth texture of the scene. Next, use a vertex shader to make the quad cover the screen at all times so that the post-processing effect will be applied at all times, including in the editor. @@ -150,7 +150,7 @@ screen quad. The reason for this is explained `here `. An +Set the Mesh in the MeshInstance to an `ArrayMesh `. An ArrayMesh is a tool that allows you to easily construct a Mesh from Arrays for vertices, normals, colors, etc. diff --git a/tutorials/shaders/converting_glsl_to_godot_shaders.rst b/tutorials/shaders/converting_glsl_to_godot_shaders.rst index 9e756d8..5592247 100644 --- a/tutorials/shaders/converting_glsl_to_godot_shaders.rst +++ b/tutorials/shaders/converting_glsl_to_godot_shaders.rst @@ -8,7 +8,7 @@ and gives practical advice on how to migrate shaders from other sources, such as Shadertoy and The Book of Shaders, into Godot shaders. For detailed information on Godot's shading language, please refer to the -:ref:`Shading Language ` reference. +`Shading Language ` reference. GLSL ---- @@ -35,7 +35,7 @@ Vertex attributes In GLSL, you can pass in per-vertex information using attributes and have the flexibility to pass in as much or as little as you want. In Godot, you have a set number of input attributes, including ``VERTEX`` (position), ``COLOR``, -``UV``, ``UV2``, ``NORMAL``. For a complete list, see the :ref:`Shading language +``UV``, ``UV2``, ``NORMAL``. For a complete list, see the `Shading language reference `. gl_Position @@ -126,7 +126,7 @@ In GLSL, you can define the precision of a given type (float or int) at the top of the shader with the ``precision`` keyword. In Godot, you can set the precision of individual variables as you need by placing precision qualifiers ``lowp``, ``mediump``, and ``highp`` before the type when defining the variable. -For more information, see the :ref:`Shading Language ` +For more information, see the `Shading Language ` reference. Shadertoy @@ -196,7 +196,7 @@ what they can pass in as a substitute. Coordinates ^^^^^^^^^^^ -``fragCoord`` behaves the same as ``gl_FragCoord`` in :ref:`GLSL +``fragCoord`` behaves the same as ``gl_FragCoord`` in `GLSL ` and ``FRAGCOORD`` in Godot. @@ -250,4 +250,4 @@ Coordinates ^^^^^^^^^^^ The Book of Shaders uses the same coordinate system as -:ref:`GLSL `. +`GLSL `. diff --git a/tutorials/shaders/custom_postprocessing.rst b/tutorials/shaders/custom_postprocessing.rst index 17edf35..4c30467 100644 --- a/tutorials/shaders/custom_postprocessing.rst +++ b/tutorials/shaders/custom_postprocessing.rst @@ -10,11 +10,11 @@ Godot provides many post-processing effects out of the box, including Bloom, DOF want to write your own custom effect. Here's how you can do so. Post-processing effects are shaders applied to a frame after Godot rendered it. You first want to render -your scene into a :ref:`Viewport `, then render the ``Viewport`` -inside a :ref:`ViewportTexture ` and show it on the screen. +your scene into a `Viewport `, then render the ``Viewport`` +inside a `ViewportTexture ` and show it on the screen. The easiest way to implement a custom post-processing shader is to use Godot's built-in ability to read from -the screen texture. If you're not familiar with this, you should read the :ref:`Screen Reading Shaders +the screen texture. If you're not familiar with this, you should read the `Screen Reading Shaders Tutorial ` first. .. note:: @@ -27,9 +27,9 @@ Single pass post-processing --------------------------- You will need a ``Viewport`` to render your scene to, and a scene to render your -``Viewport`` on the screen. You can use a :ref:`ViewportContainer +``Viewport`` on the screen. You can use a `ViewportContainer ` to display your ``Viewport`` on the entire screen or inside -another :ref:`Control ` node. +another `Control ` node. .. note:: @@ -37,7 +37,7 @@ another :ref:`Control ` node. how the scene render, including the framerate, and you can use the ``ViewportContainer`` to render 3D objects in a 2D scene. -For this demo, we will use a :ref:`Node2D ` with a ``ViewportContainer`` and finally a +For this demo, we will use a `Node2D ` with a ``ViewportContainer`` and finally a ``Viewport``. Your **Scene** tab should look like this: .. image:: img/post_hierarchy1.png @@ -47,7 +47,7 @@ your main scene. For this tutorial, we will use a field of random boxes: .. image:: img/post_boxes.png -Add a new :ref:`ShaderMaterial ` to the ``ViewportContainer``, and assign a new +Add a new `ShaderMaterial ` to the ``ViewportContainer``, and assign a new shader resource to it. You can access your rendered ``Viewport`` with the built-in ``TEXTURE`` uniform. .. note:: @@ -126,7 +126,7 @@ the tree. Apart from the node structure, the steps are the same as with the single-pass post-processing shader. As an example, you could write a full screen Gaussian blur effect by attaching the following pieces of code -to each of the :ref:`ViewportContainers `. The order in which you apply the shaders +to each of the `ViewportContainers `. The order in which you apply the shaders does not matter: .. code-block:: glsl @@ -169,4 +169,4 @@ Using the above code, you should end up with a full screen blur effect like belo .. image:: img/post_blur.png -For more information on how ``Viewport`` nodes work, see the :ref:`Viewports Tutorial `. +For more information on how ``Viewport`` nodes work, see the `Viewports Tutorial `. diff --git a/tutorials/shaders/introduction_to_shaders.rst b/tutorials/shaders/introduction_to_shaders.rst index 52233d5..d0682cf 100644 --- a/tutorials/shaders/introduction_to_shaders.rst +++ b/tutorials/shaders/introduction_to_shaders.rst @@ -5,7 +5,7 @@ Introduction to shaders This page explains what shaders are and will give you an overview of how they work in Godot. For a detailed reference of the engine's shading language, see -:ref:`doc_shading_language`. +`doc_shading_language`. Shaders are a special kind of program that runs on Graphics Processing Units (GPUs). They were initially used to shade 3D scenes but can nowadays do much @@ -84,9 +84,9 @@ In Godot, all shaders need to specify their type in the first line, like so: Here are the available types: -* :ref:`spatial ` for 3D rendering. -* :ref:`canvas_item ` for 2D rendering. -* :ref:`particles ` for particle systems. +* `spatial ` for 3D rendering. +* `canvas_item ` for 2D rendering. +* `particles ` for particle systems. Render modes ------------ @@ -126,7 +126,7 @@ can also use it to send extra data to the fragment function using varyings. By default, Godot transforms your vertex information for you, which is necessary to project geometry onto the screen. You can use render modes to transform the -data yourself; see the :ref:`Spatial shader doc ` for an +data yourself; see the `Spatial shader doc ` for an example. Fragment processor @@ -157,6 +157,6 @@ exists as a function called inside the ``fragment()`` processor and typically operates on the material properties setup inside the ``fragment()`` function. The ``light()`` processor works differently in 2D than it does in 3D; for a -description of how it works in each, see their documentation, :ref:`CanvasItem -shaders ` and :ref:`Spatial shaders +description of how it works in each, see their documentation, `CanvasItem +shaders ` and `Spatial shaders `, respectively. diff --git a/tutorials/shaders/screen-reading_shaders.rst b/tutorials/shaders/screen-reading_shaders.rst index 2ef250f..0ee65f4 100644 --- a/tutorials/shaders/screen-reading_shaders.rst +++ b/tutorials/shaders/screen-reading_shaders.rst @@ -20,7 +20,7 @@ few tools that make this process easy. SCREEN_TEXTURE built-in texture ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Godot :ref:`doc_shading_language` has a special texture, ``SCREEN_TEXTURE`` (and ``DEPTH_TEXTURE`` for depth, in the case of 3D). +Godot `doc_shading_language` has a special texture, ``SCREEN_TEXTURE`` (and ``DEPTH_TEXTURE`` for depth, in the case of 3D). It takes as argument the UV of the screen and returns a vec3 RGB with the color. A special built-in varying: SCREEN_UV can be used to obtain the UV for the current fragment. As a result, this simple canvas_item fragment shader: @@ -91,7 +91,7 @@ In the above image, the second sphere (top right) is using the same source for ``SCREEN_TEXTURE`` as the first one below, so the first one "disappears", or is not visible. -In 2D, this can be corrected via the :ref:`BackBufferCopy ` +In 2D, this can be corrected via the `BackBufferCopy ` node, which can be instantiated between both spheres. BackBufferCopy can work by either specifying a screen region or the whole screen: @@ -113,9 +113,9 @@ In 3D, there is less flexibility to solve this particular issue because the ``SCREEN_TEXTURE`` in 3D as it won't capture transparent objects and may capture some opaque objects that are in front of the object. -You can reproduce the back-buffer logic in 3D by creating a :ref:`Viewport ` +You can reproduce the back-buffer logic in 3D by creating a `Viewport ` with a camera in the same position as your object, and then use the -:ref:`Viewport's ` texture instead of ``SCREEN_TEXTURE``. +`Viewport's ` texture instead of ``SCREEN_TEXTURE``. Back-buffer logic ~~~~~~~~~~~~~~~~~ diff --git a/tutorials/shaders/shader_materials.rst b/tutorials/shaders/shader_materials.rst index f3849ff..cd5498a 100644 --- a/tutorials/shaders/shader_materials.rst +++ b/tutorials/shaders/shader_materials.rst @@ -7,8 +7,8 @@ Introduction ------------ For the most common cases, Godot provides ready to use materials for -most types of shaders, such as :ref:`SpatialMaterial `, -:ref:`CanvasItemMaterial ` and :ref:`ParticlesMaterial `. +most types of shaders, such as `SpatialMaterial `, +`CanvasItemMaterial ` and `ParticlesMaterial `. They are flexible implementations that cover most use cases. Shader materials allow writing a custom shader directly, for maximum flexibility. @@ -64,7 +64,7 @@ your visual shader to a text shader. .. note:: - To learn more about visual shaders, read :ref:`doc_visual_shaders`. + To learn more about visual shaders, read `doc_visual_shaders`. Converting to ShaderMaterial ---------------------------- diff --git a/tutorials/shaders/shader_reference/canvas_item_shader.rst b/tutorials/shaders/shader_reference/canvas_item_shader.rst index 4bb02e2..2f5afe9 100644 --- a/tutorials/shaders/shader_reference/canvas_item_shader.rst +++ b/tutorials/shaders/shader_reference/canvas_item_shader.rst @@ -53,7 +53,7 @@ Global built-ins are available everywhere, including custom functions. +===================+=============================================================================+ | in float **TIME** | Global time since the engine has started, in seconds (always positive). | | | It's subject to the rollover setting (which is 3,600 seconds by default). | -| | It's not affected by :ref:`time_scale` | +| | It's not affected by `time_scale` | | | or pausing, but you can override the ``TIME`` variable's time scale by | | | calling ``VisualServer.set_shader_time_scale()`` with the desired | | | time scale factor as parameter (``1.0`` being the default). | @@ -143,7 +143,7 @@ is usually: Fragment built-ins ^^^^^^^^^^^^^^^^^^ -Certain Nodes (for example, :ref:`Sprites `) display a texture by default. However, +Certain Nodes (for example, `Sprites `) display a texture by default. However, when a custom fragment function is attached to these nodes, the texture lookup needs to be done manually. Godot does not provide the texture color in the ``COLOR`` built-in variable; to read the texture color for such nodes, use: diff --git a/tutorials/shaders/shader_reference/shading_language.rst b/tutorials/shaders/shader_reference/shading_language.rst index 36d70c2..a6baf3d 100644 --- a/tutorials/shaders/shader_reference/shading_language.rst +++ b/tutorials/shaders/shader_reference/shading_language.rst @@ -9,7 +9,7 @@ Introduction Godot uses a shading language similar to GLSL ES 3.0. Most datatypes and functions are supported, and the few remaining ones will likely be added over time. -If you are already familiar with GLSL, the :ref:`Godot Shader Migration Guide` +If you are already familiar with GLSL, the `Godot Shader Migration Guide` is a resource that will help you transition from regular GLSL to Godot's shading language. Data types @@ -627,9 +627,9 @@ Built-in variables A large number of built-in variables are available, like ``UV``, ``COLOR`` and ``VERTEX``. What variables are available depends on the type of shader (``spatial``, ``canvas_item`` or ``particle``) and the function used (``vertex``, ``fragment`` or ``light``). For a list of the build-in variables that are available, please see the corresponding pages: -- :ref:`Spatial shaders ` -- :ref:`Canvas item shaders ` -- :ref:`Particle shaders ` +- `Spatial shaders ` +- `Canvas item shaders ` +- `Particle shaders ` Built-in functions ------------------ @@ -638,7 +638,7 @@ A large number of built-in functions are supported, conforming to GLSL ES 3.0. When vec_type (float), vec_int_type, vec_uint_type, vec_bool_type nomenclature is used, it can be scalar or vector. .. note:: For a list of the functions that are not available in the GLES2 backend, please see the - :ref:`Differences between GLES2 and GLES3 doc `. + `Differences between GLES2 and GLES3 doc `. +------------------------------------------------------------------------+---------------------------------------------------------------+ | Function | Description | diff --git a/tutorials/shaders/shader_reference/spatial_shader.rst b/tutorials/shaders/shader_reference/spatial_shader.rst index fbb3d47..7bf13f7 100644 --- a/tutorials/shaders/shader_reference/spatial_shader.rst +++ b/tutorials/shaders/shader_reference/spatial_shader.rst @@ -298,7 +298,7 @@ these properties, and if you don't write to them, Godot will optimize away the c Shaders going through the transparent pipeline when ``ALPHA`` is written to may exhibit transparency sorting issues. Read the - :ref:`transparency sorting section in the 3D rendering limitations page ` + `transparency sorting section in the 3D rendering limitations page ` for more information and ways to avoid issues. Light built-ins @@ -393,5 +393,5 @@ If you want the lights to add together, add the light contribution to ``DIFFUSE_ Shaders going through the transparent pipeline when ``ALPHA`` is written to may exhibit transparency sorting issues. Read the - :ref:`transparency sorting section in the 3D rendering limitations page ` + `transparency sorting section in the 3D rendering limitations page ` for more information and ways to avoid issues. diff --git a/tutorials/shaders/using_viewport_as_texture.rst b/tutorials/shaders/using_viewport_as_texture.rst index 6d1d712..85c04e5 100644 --- a/tutorials/shaders/using_viewport_as_texture.rst +++ b/tutorials/shaders/using_viewport_as_texture.rst @@ -6,7 +6,7 @@ Using a Viewport as a texture Introduction ------------ -This tutorial will introduce you to using the :ref:`Viewport ` as a +This tutorial will introduce you to using the `Viewport ` as a texture that can be applied to 3D objects. In order to do so, it will walk you through the process of making a procedural planet like the one below: @@ -15,42 +15,42 @@ of making a procedural planet like the one below: .. note:: This tutorial does not cover how to code a dynamic atmosphere like the one this planet has. This tutorial assumes you are familiar with how to set up a basic scene including: -a :ref:`Camera `, a :ref:`light source `, a -:ref:`Mesh Instance ` with a :ref:`Primitive Mesh `, -and applying a :ref:`SpatialMaterial ` to the mesh. The focus will be on using -the :ref:`Viewport ` to dynamically create textures that can be applied to the mesh. +a `Camera `, a `light source `, a +`Mesh Instance ` with a `Primitive Mesh `, +and applying a `SpatialMaterial ` to the mesh. The focus will be on using +the `Viewport ` to dynamically create textures that can be applied to the mesh. In this tutorial, we'll cover the following topics: -- How to use a :ref:`Viewport ` as a render texture +- How to use a `Viewport ` as a render texture - Mapping a texture to a sphere with equirectangular mapping - Fragment shader techniques for procedural planets -- Setting a Roughness map from a :ref:`Viewport Texture ` +- Setting a Roughness map from a `Viewport Texture ` Setting up the Viewport ----------------------- -First, add a :ref:`Viewport ` to the scene. +First, add a `Viewport ` to the scene. -Next, set the size of the :ref:`Viewport ` to ``(1024, 512)``. The -:ref:`Viewport ` can actually be any size so long as the width is double the height. +Next, set the size of the `Viewport ` to ``(1024, 512)``. The +`Viewport ` can actually be any size so long as the width is double the height. The width needs to be double the height so that the image will accurately map onto the sphere, as we will be using equirectangular projection, but more on that later. .. image:: img/planet_new_viewport.png Next, disable HDR and disable 3D. We don't need HDR because our planet's surface will not be especially -bright, so values between ``0`` and ``1`` will be fine. And we will be using a :ref:`ColorRect ` +bright, so values between ``0`` and ``1`` will be fine. And we will be using a `ColorRect ` to render the surface, so we don't need 3D either. -Select the Viewport and add a :ref:`ColorRect ` as a child. +Select the Viewport and add a `ColorRect ` as a child. Set the anchors "Right" and "Bottom" to ``1``, then make sure all the margins are set to ``0``. This -will ensure that the :ref:`ColorRect ` takes up the entire :ref:`Viewport `. +will ensure that the `ColorRect ` takes up the entire `Viewport `. .. image:: img/planet_new_colorrect.png -Next, we add a :ref:`Shader Material ` to the :ref:`ColorRect ` (ColorRect > CanvasItem > Material > Material > ``New ShaderMaterial``). +Next, we add a `Shader Material ` to the `ColorRect ` (ColorRect > CanvasItem > Material > Material > ``New ShaderMaterial``). .. note:: Basic familiarity with shading is recommended for this tutorial. However, even if you are new to shaders, all the code will be provided, so you should have no problem following along. @@ -69,7 +69,7 @@ The above code renders a gradient like the one below. .. image:: img/planet_gradient.png -Now we have the basics of a :ref:`Viewport ` that we render to and we have a unique image that we can +Now we have the basics of a `Viewport ` that we render to and we have a unique image that we can apply to the sphere. Applying the texture @@ -77,13 +77,13 @@ Applying the texture MeshInstance > GeometryInstance > Geometry > Material Override > ``New SpatialMaterial``: -Now we go into the :ref:`Mesh Instance ` and add a :ref:`SpatialMaterial ` -to it. No need for a special :ref:`Shader Material ` (although that would be a good idea +Now we go into the `Mesh Instance ` and add a `SpatialMaterial ` +to it. No need for a special `Shader Material ` (although that would be a good idea for more advanced effects, like the atmosphere in the example above). MeshInstance > GeometryInstance > Geometry > Material Override > ``click`` / ``Edit``: -Open the newly created :ref:`SpatialMaterial ` and scroll down to the "Albedo" section +Open the newly created `SpatialMaterial ` and scroll down to the "Albedo" section and click beside the "Texture" property to add an Albedo Texture. Here we will apply the texture we made. Choose "New ViewportTexture" @@ -106,7 +106,7 @@ problem that we will illustrate in the next section. Making the planet texture ------------------------- -So now, when we render to our :ref:`Viewport `, it appears magically on the sphere. But there is an ugly +So now, when we render to our `Viewport `, it appears magically on the sphere. But there is an ugly seam created by our texture coordinates. So how do we get a range of coordinates that wrap around the sphere in a nice way? One solution is to use a function that repeats on the domain of our texture. ``sin`` and ``cos`` are two such functions. Let's apply them to the texture and see what happens. @@ -119,7 +119,7 @@ the sphere in a nice way? One solution is to use a function that repeats on the Not too bad. If you look around, you can see that the seam has now disappeared, but in its place, we have pinching at the poles. This pinching is due to the way Godot maps textures to spheres in its -:ref:`SpatialMaterial `. It uses a projection technique called equirectangular +`SpatialMaterial `. It uses a projection technique called equirectangular projection, which translates a spherical map onto a 2D plane. .. note:: If you are interested in a little extra information on the technique, we will be converting from @@ -273,7 +273,7 @@ And then, in the material, under the "Metallic" section, make sure ``Metallic`` isn't metallic. These values are not physically accurate, but they are good enough for this demo. Next, under the "Roughness" section, set ``Roughness`` to ``1`` and set the roughness texture to a -:ref:`Viewport Texture ` pointing to our planet texture :ref:`Viewport `. +`Viewport Texture ` pointing to our planet texture `Viewport `. Finally, set the ``Texture Channel`` to ``Alpha``. This instructs the renderer to use the ``alpha`` channel of our output ``COLOR`` as the ``Roughness`` value. @@ -282,10 +282,10 @@ channel of our output ``COLOR`` as the ``Roughness`` value. You'll notice that very little changes except that the planet is no longer reflecting the sky. This is happening because, by default, when something is rendered with an alpha value, it gets drawn as a transparent object over the background. And since the default background -of the :ref:`Viewport ` is opaque, the ``alpha`` channel of the -:ref:`Viewport Texture ` is ``1``, resulting in the planet texture being +of the `Viewport ` is opaque, the ``alpha`` channel of the +`Viewport Texture ` is ``1``, resulting in the planet texture being drawn with slightly fainter colors and a ``Roughness`` value of ``1`` everywhere. To correct this, we -go into the :ref:`Viewport ` and enable the "Transparent Bg" property. Since we are now +go into the `Viewport ` and enable the "Transparent Bg" property. Since we are now rendering one transparent object on top of another, we want to enable ``blend_premul_alpha``: .. code-block:: glsl @@ -297,9 +297,9 @@ when blending one transparent color on top of another, even if the background ha does in this case), you end up with weird color bleed issues. Setting ``blend_premul_alpha`` fixes that. Now the planet should look like it is reflecting light on the ocean but not the land. If you haven't done -so already, add an :ref:`OmniLight ` to the scene so you can move it around and see the +so already, add an `OmniLight ` to the scene so you can move it around and see the effect of the reflections on the ocean. .. image:: img/planet_ocean_reflect.png -And there you have it. A procedural planet generated using a :ref:`Viewport `. +And there you have it. A procedural planet generated using a `Viewport `. diff --git a/tutorials/shaders/your_first_shader/index.rst b/tutorials/shaders/your_first_shader/index.rst index 00bc69e..4f2c7d8 100644 --- a/tutorials/shaders/your_first_shader/index.rst +++ b/tutorials/shaders/your_first_shader/index.rst @@ -5,7 +5,7 @@ This tutorial series will walk you through writing your first shader. It is inte for people who have very little prior experience with shaders and want to get started with the basics. This tutorial will not cover advanced topics and it is not comprehensive. For a comprehensive and detailed overview of shaders in Godot see the -:ref:`Shading Reference Page `. +`Shading Reference Page `. The "your first shader" tutorials walk you through the process of writing a shader step-by-step. diff --git a/tutorials/shaders/your_first_shader/your_first_2d_shader.rst b/tutorials/shaders/your_first_shader/your_first_2d_shader.rst index 6339a2b..e2285be 100644 --- a/tutorials/shaders/your_first_shader/your_first_2d_shader.rst +++ b/tutorials/shaders/your_first_shader/your_first_2d_shader.rst @@ -8,7 +8,7 @@ Introduction Shaders are special programs that execute on the GPU and are used for rendering graphics. All modern rendering is done with shaders. For a more detailed -description of what shaders are please see :ref:`What are shaders +description of what shaders are please see `What are shaders `. This tutorial will focus on the practical aspects of writing shader programs by @@ -16,24 +16,24 @@ walking you through the process of writing a shader with both vertex and fragment functions. This tutorial targets absolute beginners to shaders. .. note:: If you have experience writing shaders and are just looking for an - overview of how shaders work in Godot, see the :ref:`Shading Reference + overview of how shaders work in Godot, see the `Shading Reference `. Setup ----- -:ref:`CanvasItem ` shaders are used to draw all 2D - objects in Godot, while :ref:`Spatial ` shaders are +`CanvasItem ` shaders are used to draw all 2D + objects in Godot, while `Spatial ` shaders are used to draw all 3D objects. -In order to use a shader it must be attached inside a :ref:`Material +In order to use a shader it must be attached inside a `Material ` which must be attached to an object. Materials are a type of -:ref:`Resource `. To draw multiple objects with the same +`Resource `. To draw multiple objects with the same material, the material must be attached to each object. -All objects derived from a :ref:`CanvasItem ` have a material -property. This includes all :ref:`GUI elements `, :ref:`Sprites -`, :ref:`TileMaps `, :ref:`MeshInstance2Ds +All objects derived from a `CanvasItem ` have a material +property. This includes all `GUI elements `, `Sprites +`, `TileMaps `, `MeshInstance2Ds ` etc. They also have an option to inherit their parent's material. This can be useful if you have a large number of nodes that you want to use the same material. @@ -92,7 +92,7 @@ every pixel. We do so by writing a ``vec4`` to the built-in variable ``COLOR``. ``vec4`` is shorthand for constructing a vector with 4 numbers. For more information about -vectors see the :ref:`Vector math tutorial ` ``COLOR`` is both +vectors see the `Vector math tutorial ` ``COLOR`` is both an input variable to the fragment function and the final output from it. .. code-block:: glsl @@ -169,7 +169,7 @@ You can use uniforms by defining them at the top of your shader like so: uniform float size; -For more information about usage see the :ref:`Shading Language doc +For more information about usage see the `Shading Language doc `. Add a uniform to change the amount of blue in our Sprite. diff --git a/tutorials/shaders/your_first_shader/your_first_3d_shader.rst b/tutorials/shaders/your_first_shader/your_first_3d_shader.rst index 5a77d7f..1c22f24 100644 --- a/tutorials/shaders/your_first_shader/your_first_3d_shader.rst +++ b/tutorials/shaders/your_first_shader/your_first_3d_shader.rst @@ -5,12 +5,12 @@ Your first 3D shader You have decided to start writing your own custom Spatial shader. Maybe you saw a cool trick online that was done with shaders, or you have found that the -:ref:`SpatialMaterial ` isn't quite meeting your +`SpatialMaterial ` isn't quite meeting your needs. Either way, you have decided to write your own and now you need to figure out where to start. This tutorial will explain how to write a Spatial shader and will cover more -topics than the :ref:`CanvasItem ` tutorial. +topics than the `CanvasItem ` tutorial. Spatial shaders have more built-in functionality than CanvasItem shaders. The expectation with spatial shaders is that Godot has already provided the @@ -20,7 +20,7 @@ rendering) workflow. This is a two-part tutorial. In this first part we are going to go through how to make a simple terrain using vertex displacement from a heightmap in the -vertex function. In the :ref:`second part ` we +vertex function. In the `second part ` we are going to take the concepts from this tutorial and walk through how to set up custom materials in a fragment shader by writing an ocean water shader. @@ -33,18 +33,18 @@ custom materials in a fragment shader by writing an ocean water shader. Where to assign my material --------------------------- -In 3D, objects are drawn using :ref:`Meshes `. Meshes are a resource +In 3D, objects are drawn using `Meshes `. Meshes are a resource type that store geometry (the shape of your object) and materials (the color and how the object reacts to light) in units called "surfaces". A Mesh can have multiple surfaces, or just one. Typically, you would import a mesh from another -program (e.g. Blender). But Godot also has a few :ref:`PrimitiveMeshes +program (e.g. Blender). But Godot also has a few `PrimitiveMeshes ` that allow you to add basic geometry to a scene without importing Meshes. There are multiple node types that you can use to draw a mesh. The main one is -:ref:`MeshInstance `, but you can also use :ref:`Particles -`, :ref:`MultiMeshes ` (with a -:ref:`MultiMeshInstance `), or others. +`MeshInstance `, but you can also use `Particles +`, `MultiMeshes ` (with a +`MultiMeshInstance `), or others. Typically, a material is associated with a given surface in a mesh, but some nodes, like MeshInstance, allow you to override the material for a specific @@ -61,12 +61,12 @@ advantage of the MeshInstance's ability to override materials. Setting up ---------- -Add a new :ref:`MeshInstance ` node to your scene. +Add a new `MeshInstance ` node to your scene. In the inspector tab beside "Mesh" click "[empty]" and select "New PlaneMesh". Then click on the image of a plane that appears. -This adds a :ref:`PlaneMesh ` to our scene. +This adds a `PlaneMesh ` to our scene. Then, in the viewport, click in the upper left corner on the button that says "Perspective". A menu will appear. In the middle of the menu are options for how @@ -81,12 +81,12 @@ Now set ``Subdivide Width`` and ``Subdivide Depth`` to ``32``. .. image:: img/plane-sub-set.png You can see that there are now many more triangles in the -:ref:`Mesh`. This will give us more vertices to work with +`Mesh`. This will give us more vertices to work with and thus allow us to add more detail. .. image:: img/plane-sub.png -:ref:`PrimitiveMeshes `, like PlaneMesh, only have one +`PrimitiveMeshes `, like PlaneMesh, only have one surface, so instead of an array of materials there is only one. Click beside "Material" where it says "[empty]" and select "New ShaderMaterial". Then click the sphere that appears. @@ -111,7 +111,7 @@ because this is a spatial shader. shader_type spatial; Next we will define the ``vertex()`` function. The ``vertex()`` function -determines where the vertices of your :ref:`Mesh` appear in +determines where the vertices of your `Mesh` appear in the final scene. We will be using it to offset the height of each vertex and make our flat plane appear like a little terrain. @@ -163,7 +163,7 @@ Noise is a very popular tool for faking the look of terrain. Think of it as similar to the cosine function where you have repeating hills except, with noise, each hill has a different height. -Godot provides the :ref:`NoiseTexture ` resource for +Godot provides the `NoiseTexture ` resource for generating a noise texture that can be accessed from a shader. To access a texture in a shader add the following code near the top of your @@ -181,7 +181,7 @@ Click beside it where it says "[empty]" and select "New NoiseTexture". Then in your NoiseTexture click beside where it says "Noise" and select "New OpenSimplexNoise". -:ref:`OpenSimplexNoise ` is used by the NoiseTexture to +`OpenSimplexNoise ` is used by the NoiseTexture to generate a heightmap. Once you set it up and should look like this. @@ -223,7 +223,7 @@ Uniforms Uniform variables allow you to pass data from the game into the shader. They are very useful for controlling shader effects. Uniforms can be almost any datatype that can be used in the shader. To use a uniform, you declare it in your -:ref:`Shader` using the keyword ``uniform``. +`Shader` using the keyword ``uniform``. Let's make a uniform that changes the height of the terrain. @@ -251,8 +251,8 @@ the shader. ``get_surface_material()`` or ``material_override``. Remember that the string passed into ``set_shader_param()`` must match the name -of the uniform variable in the :ref:`Shader`. You can use the -uniform variable anywhere inside your :ref:`Shader`. Here, we will +of the uniform variable in the `Shader`. You can use the +uniform variable anywhere inside your `Shader`. Here, we will use it to set the height value instead of arbitrarily multiplying by ``0.5``. .. code-block:: glsl @@ -264,7 +264,7 @@ Now it looks much better. .. image:: img/noise-low.png Using uniforms, we can even change the value every frame to animate the height -of the terrain. Combined with :ref:`Tweens `, this can be +of the terrain. Combined with `Tweens `, this can be especially useful for simple animations. Interacting with light @@ -278,13 +278,13 @@ again, where it says "Perspective", and select "Display Normal". Note how the mesh color goes flat. This is because the lighting on it is flat. Let's add a light! -First, we will add an :ref:`OmniLight` to the scene. +First, we will add an `OmniLight` to the scene. .. image:: img/light.png You can see the light affecting the terrain, but it looks odd. The problem is the light is affecting the terrain as if it were a flat plane. This is because -the light shader uses the normals from the :ref:`Mesh ` to calculate +the light shader uses the normals from the `Mesh ` to calculate light. The normals are stored in the Mesh, but we are changing the shape of the Mesh in diff --git a/tutorials/shaders/your_first_shader/your_second_3d_shader.rst b/tutorials/shaders/your_first_shader/your_second_3d_shader.rst index fdaf42c..24dd5d9 100644 --- a/tutorials/shaders/your_first_shader/your_second_3d_shader.rst +++ b/tutorials/shaders/your_first_shader/your_second_3d_shader.rst @@ -12,13 +12,13 @@ the extra feature. This makes it easy for users to have complex PBR-correct shading, without writing complex shaders. Of course, Godot also allows you to ignore all these parameters and write a fully customized shader. -For a full list of these parameters see the :ref:`spatial shader +For a full list of these parameters see the `spatial shader ` reference doc. A difference between the vertex function and a fragment function is that the vertex function runs per vertex and sets properties such as ``VERTEX`` (position) and ``NORMAL``, while the fragment shader runs per pixel and, most -importantly, sets the ``ALBEDO`` color of the :ref:`Mesh`. +importantly, sets the ``ALBEDO`` color of the `Mesh`. Your first spatial fragment function ------------------------------------ @@ -48,7 +48,7 @@ specular mode to toon: This model of built-in functionality allows you to write complex custom shaders by changing only a few parameters. -For a full list of render modes see the :ref:`Spatial shader reference +For a full list of render modes see the `Spatial shader reference `. In this part of the tutorial, we will walk through how to take the bumpy terrain @@ -343,8 +343,8 @@ to do was add a bit of math! .. image:: img/wave3.png -For more information about Spatial shaders read the :ref:`Shading Language -` doc and the :ref:`Spatial Shaders ` -doc. Also look at more advanced tutorials in the :ref:`Shading section -` and the :ref:`3D ` +For more information about Spatial shaders read the `Shading Language +` doc and the `Spatial Shaders ` +doc. Also look at more advanced tutorials in the `Shading section +` and the `3D ` sections. diff --git a/tutorials/ui/bbcode_in_richtextlabel.rst b/tutorials/ui/bbcode_in_richtextlabel.rst index 0f6ceb5..e133550 100644 --- a/tutorials/ui/bbcode_in_richtextlabel.rst +++ b/tutorials/ui/bbcode_in_richtextlabel.rst @@ -10,13 +10,13 @@ Label nodes are great for displaying basic text, but they have limits. If you wa to change the color of the text, or its alignment, that change affects all of the text in the Label node. You can't have only one part of the text be one color, or only one part of the text be centered. To get around this limitation you would use -a :ref:`class_RichTextLabel`. +a `class_RichTextLabel`. -:ref:`class_RichTextLabel` allows the display of complex text markup in a Control. +`class_RichTextLabel` allows the display of complex text markup in a Control. It has a built-in API for generating the markup, but can also parse a BBCode. Note that the BBCode tags can also be used, to some extent, in the -:ref:`XML source of the class reference `. +`XML source of the class reference `. Using BBCode ------------ @@ -72,11 +72,11 @@ Reference +-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+ | **url** | ``[url]{url}[/url]`` | Show {url} as such, underline it and make it clickable. | | | | **Must be handled with the "meta_clicked" signal to have an effect.** | -| | | See :ref:`doc_bbcode_in_richtextlabel_handling_url_tag_clicks`. | +| | | See `doc_bbcode_in_richtextlabel_handling_url_tag_clicks`. | +-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+ | **url (ref)** | ``[url=]{text}[/url]`` | Makes {text} reference (underlined and clickable). | | | | **Must be handled with the "meta_clicked" signal to have an effect.** | -| | | See :ref:`doc_bbcode_in_richtextlabel_handling_url_tag_clicks`. | +| | | See `doc_bbcode_in_richtextlabel_handling_url_tag_clicks`. | +-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+ | **image** | ``[img]{path}[/img]`` | Insert image at resource {path}. | +-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+ @@ -133,7 +133,7 @@ By default, ``[url]`` tags do nothing when clicked. This is to allow flexible us of ``[url]`` tags rather than limiting them to opening URLs in a web browser. To handle clicked ``[url]`` tags, connect the RichTextLabel node's -:ref:`meta_clicked ` signal to a script function. +`meta_clicked ` signal to a script function. For example, the following method can be connected to ``meta_clicked`` to open clicked URLs using the user's default web browser:: @@ -216,8 +216,8 @@ of the rainbow, ``val`` is the value of the rainbow. Custom BBCode tags and text effects ----------------------------------- -You can extend the :ref:`class_RichTextEffect` resource type to create your own custom -BBCode tags. You begin by extending the :ref:`class_RichTextEffect` resource type. Add +You can extend the `class_RichTextEffect` resource type to create your own custom +BBCode tags. You begin by extending the `class_RichTextEffect` resource type. Add the ``tool`` prefix to your GDScript file if you wish to have these custom effects run within the editor itself. The RichTextLabel does not need to have a script attached, nor does it need to be running in ``tool`` mode. The new effect will be activable in @@ -238,7 +238,7 @@ use the name of the file to determine what the BBCode tag should be. ~~~~~~~~~~~~~~~~~~~~~~ This is where the logic of each effect takes place and is called once per character -during the draw phase of text rendering. This passes in a :ref:`class_CharFXTransform` +during the draw phase of text rendering. This passes in a `class_CharFXTransform` object, which holds a few variables to control how the associated character is rendered: - ``identity`` specifies which custom effect is being processed. You should use that for @@ -252,8 +252,8 @@ object, which holds a few variables to control how the associated character is r - ``offset`` is an offset position relative to where the given character should render under normal circumstances. - ``color`` is the color of a given character. -- Finally, ``env`` is a :ref:`class_Dictionary` of parameters assigned to a given custom - effect. You can use :ref:`get() ` with an optional default value +- Finally, ``env`` is a `class_Dictionary` of parameters assigned to a given custom + effect. You can use `get() ` with an optional default value to retrieve each parameter, if specified by the user. For example ``[custom_fx spread=0.5 color=#FFFF00]test[/custom_fx]`` would have a float ``spread`` and Color ``color`` parameters in its ` `env`` Dictionary. See below for more usage examples. diff --git a/tutorials/ui/custom_gui_controls.rst b/tutorials/ui/custom_gui_controls.rst index 10ee32f..d05c5ae 100644 --- a/tutorials/ui/custom_gui_controls.rst +++ b/tutorials/ui/custom_gui_controls.rst @@ -16,7 +16,7 @@ create these controls easily from script. Drawing ------- -For drawing, it is recommended to check the :ref:`doc_custom_drawing_in_2d` tutorial. +For drawing, it is recommended to check the `doc_custom_drawing_in_2d` tutorial. The same applies. Some functions are worth mentioning due to their usefulness when drawing, so they will be detailed next: @@ -25,7 +25,7 @@ Checking control size Unlike 2D nodes, "size" is important with controls, as it helps to organize them in proper layouts. For this, the -:ref:`Control.rect_size ` +`Control.rect_size ` property is provided. Checking it during ``_draw()`` is vital to ensure everything is kept in-bounds. @@ -35,11 +35,11 @@ Checking focus Some controls (such as buttons or text editors) might provide input focus for keyboard or joypad input. Examples of this are entering text or pressing a button. This is controlled with the -:ref:`Control.focus_mode ` +`Control.focus_mode ` property. When drawing, and if the control supports input focus, it is always desired to show some sort of indicator (highlight, box, etc.) to indicate that this is the currently focused control. To check for this -status, the :ref:`Control.has_focus() ` method +status, the `Control.has_focus() ` method exists. Example gdscript GDScript @@ -59,12 +59,12 @@ As mentioned before, size is important to controls. This allows them to lay out properly, when set into grids, containers, or anchored. Controls, most of the time, provide a *minimum size* to help properly lay them out. For example, if controls are placed vertically on top of -each other using a :ref:`VBoxContainer `, +each other using a `VBoxContainer `, the minimum size will make sure your custom control is not squished by the other controls in the container. To provide this callback, just override -:ref:`Control.get_minimum_size() `, +`Control.get_minimum_size() `, for example: gdscript GDScript @@ -100,10 +100,10 @@ when: - The button was pressed over this control (control always captures input until button is released) - Control provides keyboard/joypad focus via - :ref:`Control.focus_mode `. + `Control.focus_mode `. This function is -:ref:`Control._gui_input() `. +`Control._gui_input() `. Simply override it in your control. No processing needs to be set. gdscript GDScript @@ -116,7 +116,7 @@ gdscript GDScript print("Left mouse button was pressed!") ``` -For more information about events themselves, check the :ref:`doc_inputevent` +For more information about events themselves, check the `doc_inputevent` tutorial. Notifications diff --git a/tutorials/ui/gui_containers.rst b/tutorials/ui/gui_containers.rst index 404162a..d837012 100644 --- a/tutorials/ui/gui_containers.rst +++ b/tutorials/ui/gui_containers.rst @@ -3,7 +3,7 @@ Using Containers ================ -:ref:`Anchors ` are an efficient way to handle +`Anchors ` are an efficient way to handle different aspect ratios for basic multiple resolution handling in GUIs, For more complex user interfaces, they can become difficult to use. @@ -12,7 +12,7 @@ This is often the case of games, such as RPGs, online chats, tycoons or simulati common case where more advanced layout features may be required is in-game tools (or simply just tools). All these situations require a more capable OS-like user interface, with advanced layout and formatting. -For that, :ref:`Containers ` are more useful. +For that, `Containers ` are more useful. Container layout ---------------- @@ -21,7 +21,7 @@ Containers provide a huge amount of layout power (as an example, the Godot edito .. image:: img/godot_containers.png -When a :ref:`Container `-derived node is used, all children :ref:`Control ` nodes give up their +When a `Container `-derived node is used, all children `Control ` nodes give up their own positioning ability. This means the *Container* will control their positioning and any attempt to manually alter these nodes will be either ignored or invalidated the next time their parent is resized. @@ -64,8 +64,8 @@ Godot provides several container types out of the box as they serve different pu Box Containers ^^^^^^^^^^^^^^ -Arranges child controls vertically or horizontally (via :ref:`HBoxContainer ` and -:ref:`VBoxContainer `). In the opposite of the designated direction +Arranges child controls vertically or horizontally (via `HBoxContainer ` and +`VBoxContainer `). In the opposite of the designated direction (as in, vertical for an horizontal container), it just expands the children. .. image:: img/containers_box.png @@ -75,7 +75,7 @@ These containers make use of the *Ratio* property for children with the *Expand* Grid Container ^^^^^^^^^^^^^^ -Arranges child controls in a grid layout (via :ref:`GridContainer `, amount +Arranges child controls in a grid layout (via `GridContainer `, amount of columns must be specified). Uses both the vertical and horizontal expand flags. .. image:: img/containers_grid.png @@ -84,7 +84,7 @@ Margin Container ^^^^^^^^^^^^^^^^ Child controls are expanded towards the bounds of this control (via -:ref:`MarginContainer `). Padding will be added on the margins +`MarginContainer `). Padding will be added on the margins depending on the theme configuration. .. image:: img/containers_margin.png @@ -98,7 +98,7 @@ Tab Container ^^^^^^^^^^^^^ Allows you to place several child controls stacked on top of each other (via -:ref:`TabContainer `), with only the *current* one visible. +`TabContainer `), with only the *current* one visible. .. image:: img/containers_tab.png @@ -114,7 +114,7 @@ Split Container ^^^^^^^^^^^^^^^ Accepts only one or two children controls, then places them side to side with a divisor -(via :ref:`HSplitContainer ` and :ref:`VSplitContainer `). +(via `HSplitContainer ` and `VSplitContainer `). Respects both horizontal and vertical flags, as well as *Ratio*. .. image:: img/containers_split.png @@ -128,7 +128,7 @@ PanelContainer ^^^^^^^^^^^^^^ Simple container that draws a *StyleBox*, then expands children to cover its whole area -(via :ref:`PanelContainer `, respecting the *StyleBox* margins). +(via `PanelContainer `, respecting the *StyleBox* margins). It respects both the horizontal and vertical size flags. .. image:: img/containers_panel.png @@ -139,7 +139,7 @@ ScrollContainer ^^^^^^^^^^^^^^^ Accepts a single child node. If this node is bigger than the container, scrollbars will be added -to allow panning the node around (via :ref:`ScrollContainer `). Both +to allow panning the node around (via `ScrollContainer `). Both vertical and horizontal size flags are respected, and the behavior can be turned on or off per axis in the properties. @@ -156,7 +156,7 @@ ViewportContainer ^^^^^^^^^^^^^^^^^ This is a special control that will only accept a single *Viewport* node as child, and it will display -it as if it was an image (via :ref:`ViewportContainer `). +it as if it was an image (via `ViewportContainer `). Creating custom Containers -------------------------- diff --git a/tutorials/ui/gui_navigation.rst b/tutorials/ui/gui_navigation.rst index 57ab96a..affa24b 100644 --- a/tutorials/ui/gui_navigation.rst +++ b/tutorials/ui/gui_navigation.rst @@ -7,12 +7,12 @@ It is a common requirement for a user interface to have full keyboard and controller support for navigation and interaction. There are two main reasons why this is beneficial for projects: improved accessibility (not everyone can use mouse or touch controls for interactions), and getting your project -ready for :ref:`consoles ` (or just for people who prefer +ready for `consoles ` (or just for people who prefer to game with a controller on PC). Navigating between UI elements with keyboard or controller is done by changing which node is actively selected. This is also called changing UI focus. -Every :ref:`Control ` node in Godot is capable of having focus. +Every `Control ` node in Godot is capable of having focus. By default, some control nodes have the ability to automatically grab focus reacting to built-in UI actions such as ``ui_up``, ``ui_down``, ``ui_focus_next``, etc. These actions can be seen in the project settings in the input map and can be modified. @@ -47,8 +47,8 @@ be focused by clicking on it with the mouse, or selecting it with a keyboard or controller. **Click** means it can only be focused on by clicking on it. Finally, **None** means it can't be focused at all. Different control nodes have different default settings for this based on how they are typically used, for -example, :ref:`Label ` nodes are set to "None" by default, -while :ref:`buttons ` are set to "All". +example, `Label ` nodes are set to "None" by default, +while `buttons ` are set to "All". Make sure to properly configure your scenes for focus and navigation. If a node has no focus neighbor configured, the engine will try to guess the next control automatically. diff --git a/tutorials/ui/gui_skinning.rst b/tutorials/ui/gui_skinning.rst index 988a114..01fc794 100644 --- a/tutorials/ui/gui_skinning.rst +++ b/tutorials/ui/gui_skinning.rst @@ -4,7 +4,7 @@ Introduction to GUI skinning ============================ It is essential for a game to provide clear, informative, and yet visually -pleasing user interface to its players. While :ref:`Control ` +pleasing user interface to its players. While `Control ` nodes come with a decently functional look out of the box, there is always room for uniqueness and case-specific tuning. For this purpose Godot engine includes a system for GUI skinning (or theming), which allows you to customize @@ -30,19 +30,19 @@ flavors to the sides in your team-based project. Basics of themes ---------------- -The skinning system is driven by the :ref:`Theme ` resource. Every +The skinning system is driven by the `Theme ` resource. Every Godot project has an inherent default theme that contains the settings used by the built-in control nodes. This is what gives the controls their distinct look out of the box. A theme only describes the configuration, however, and it is still the job of each individual control to use that configuration in the way it requires to display itself. This is important to remember when implementing -:ref:`your own custom controls `. +`your own custom controls `. .. note:: Even the Godot editor itself relies on the default theme. But it doesn't look the same as a Godot project, because it applies its own heavily customized theme on top of the default one. In principle, this works exactly like it would in your game - as explained :ref:`below `. + as explained `below `. Theme items ~~~~~~~~~~~ @@ -52,33 +52,33 @@ a unique name and must be one of the following data types: - **Color** - A :ref:`color ` value, which is often used for fonts + A `color ` value, which is often used for fonts and backgrounds. Colors can also be used for modulation of controls and icons. - **Constant** An integer value, which can be used either for numeric properties of - controls (such as the item separation in a :ref:`BoxContainer `), - or for boolean flags (such as the drawing of relationship lines in a :ref:`Tree `). + controls (such as the item separation in a `BoxContainer `), + or for boolean flags (such as the drawing of relationship lines in a `Tree `). - **Font** - A :ref:`font ` resource, which is used by controls that + A `font ` resource, which is used by controls that display text. Fonts contain most text rendering settings, except for its size and color. On top of that, alignment and text direction are controlled by individual controls. - **Icon** - A :ref:`texture ` resource, which is normally used - to display an icon (on a :ref:`Button `, for example). + A `texture ` resource, which is normally used + to display an icon (on a `Button `, for example). - **StyleBox** - A :ref:`StyleBox ` resource, a collection of configuration + A `StyleBox ` resource, a collection of configuration options which define the way a UI panel should be displayed. This is - not limited to the :ref:`Panel ` control, as styleboxes + not limited to the `Panel ` control, as styleboxes are used by many controls for their backgrounds and overlays. Theme types @@ -139,7 +139,7 @@ control node in the single ``Theme`` resource. two places, but it is recommended to keep all variations to the project theme. You can learn more about creating and using theme type variations in a -:ref:`dedicated article `. +`dedicated article `. Customizing a control --------------------- @@ -156,9 +156,9 @@ including this control's children. Local overrides are less useful for the visual flair of your user interface, especially if you aim for consistency. However, for layout nodes these are -essential. Nodes such as :ref:`BoxContainer ` and -:ref:`GridContainer ` use theme constants for defining -separation between their children, and :ref:`MarginContainer ` +essential. Nodes such as `BoxContainer ` and +`GridContainer ` use theme constants for defining +separation between their children, and `MarginContainer ` stores its customizable margins in its theme items. Whenever a control has a local theme item override, this is the value that @@ -175,15 +175,15 @@ with a custom theme. Custom themes can be applied in two ways: as a project sett and as a node property throughout the tree of control nodes. There are two project settings that can be adjusted to affect your entire project: -:ref:`gui/theme/custom` allows you to -set a custom project-wide theme, and :ref:`gui/theme/custom_font` +`gui/theme/custom` allows you to +set a custom project-wide theme, and `gui/theme/custom_font` does the same to the default fallback font. When a theme item is requested by a control node the custom project theme, if present, is checked first. Only if it doesn't have the item the default theme is checked. This allows you to configure the default look of every Godot control with a single theme resource, but you can go more granular than that. Every control node also has -a :ref:`theme ` property, which allows you to set a +a `theme ` property, which allows you to set a custom theme for the branch of nodes starting with that control. This means that the control and all of its children, and their children in turn, would first check that custom theme resource before falling back on the project and the default themes. diff --git a/tutorials/ui/gui_theme_type_variations.rst b/tutorials/ui/gui_theme_type_variations.rst index 3629f76..2a45df1 100644 --- a/tutorials/ui/gui_theme_type_variations.rst +++ b/tutorials/ui/gui_theme_type_variations.rst @@ -3,8 +3,8 @@ Theme type variations ===================== -When designing a user interface there may be times when a :ref:`Control ` node -needs to have a different look than what is normally defined by a :ref:`Theme `. +When designing a user interface there may be times when a `Control ` node +needs to have a different look than what is normally defined by a `Theme `. Every control node has theme property overrides, which allow you to redefine the styling for each individual UI element. @@ -12,11 +12,11 @@ each individual UI element. :align: center This approach quickly becomes hard to manage, if you need to share the same custom look -between several controls. Imagine that you use gray, blue, and red variants of :ref:`Button ` +between several controls. Imagine that you use gray, blue, and red variants of `Button ` throughout your project. Setting it up every time you add a new button element to your interface is a tedious task. -To help with the organization and to better utilize the :ref:`power of themes ` +To help with the organization and to better utilize the `power of themes ` you can use theme type variations. These work like normal theme types, but instead of being self-sufficient and standalone they extend another, base type. @@ -33,7 +33,7 @@ a combination of both types giving priority to the type variation. .. note:: The way controls resolve what theme items they use from each type and each - theme is better described in the :ref:`Customizing a project ` + theme is better described in the `Customizing a project ` section of the "Introduction to GUI skinning" article. Creating a type variation diff --git a/tutorials/ui/gui_using_theme_editor.rst b/tutorials/ui/gui_using_theme_editor.rst index 15116ef..9427ef1 100644 --- a/tutorials/ui/gui_using_theme_editor.rst +++ b/tutorials/ui/gui_using_theme_editor.rst @@ -5,10 +5,10 @@ Using the theme editor This articles explains how to create and manage UI themes using the Godot editor and its theme editor tool. We recommend getting familiar with the -basics behind GUI skinning/theming by reading :ref:`doc_gui_skinning` before starting. +basics behind GUI skinning/theming by reading `doc_gui_skinning` before starting. The theme editor is a bottom panel tool that activates automatically, when -a :ref:`Theme ` resource is selected for editing. It contains +a `Theme ` resource is selected for editing. It contains the necessary UI for adding, removing, and adjusting theme types and theme items. It features a preview section for testing your changes live, as well as a window dialog for doing bulk operations of the theme items. @@ -34,7 +34,7 @@ menu to save the new theme to a file instead. While the theme editor provides the tools to manage theme types and items, themes also include the default, fallback font that you can edit only using the Inspector dock. -Same applies to the contents of complex resource types, such as :ref:`StyleBoxes ` +Same applies to the contents of complex resource types, such as `StyleBoxes ` and icons — they open for editing in the Inspector. .. figure:: img/default_font.png