diff --git a/tutorials/legal/complying_with_licenses.rst b/about/complying_with_licenses.rst similarity index 100% rename from tutorials/legal/complying_with_licenses.rst rename to about/complying_with_licenses.rst diff --git a/about/docs_changelog.rst b/about/docs_changelog.rst index 5a00b0eb4..5f9ea448b 100644 --- a/about/docs_changelog.rst +++ b/about/docs_changelog.rst @@ -50,7 +50,7 @@ Shading ^^^^^^^ - Your First Shader Series: - - :ref:`doc_what_are_shaders` + - :ref:`doc_introduction_to_shaders` - :ref:`doc_your_first_canvasitem_shader` - :ref:`doc_your_first_spatial_shader` - :ref:`doc_your_second_spatial_shader` @@ -107,7 +107,7 @@ Step by step ^^^^^^^^^^^^ - :ref:`doc_signals` -- :ref:`doc_exporting` +- :ref:`doc_exporting_basics` Scripting ^^^^^^^^^ @@ -169,13 +169,12 @@ Viewports Shading ^^^^^^^ -- :ref:`doc_intro_to_shaders_water_workshop` -- :ref:`doc_migrating_to_godot_shader_language` +- :ref:`doc_converting_glsl_to_godot_shaders` - :ref:`doc_advanced_postprocessing` Shading Reference: -- :ref:`doc_shaders` +- :ref:`doc_introduction_to_shaders` - :ref:`doc_shading_language` - :ref:`doc_spatial_shader` - :ref:`doc_canvas_item_shader` diff --git a/about/faq.rst b/about/faq.rst index b29701961..ba01f1289 100644 --- a/about/faq.rst +++ b/about/faq.rst @@ -409,6 +409,8 @@ This custom UI toolkit :ref:`can't be used as a library `. +.. _doc_faq_why_not_stl: + Why does Godot not use STL (Standard Template Library)? ------------------------------------------------------- diff --git a/about/index.rst b/about/index.rst index 4552c7a1e..5a3f59959 100644 --- a/about/index.rst +++ b/about/index.rst @@ -11,6 +11,7 @@ About list_of_features docs_changelog release_policy + complying_with_licenses .. history .. authors diff --git a/classes/class_arraymesh.rst b/classes/class_arraymesh.rst index 429908806..a4cb937b0 100644 --- a/classes/class_arraymesh.rst +++ b/classes/class_arraymesh.rst @@ -45,7 +45,7 @@ See also :ref:`ImmediateGeometry`, :ref:`MeshDataTool`__ diff --git a/classes/class_control.rst b/classes/class_control.rst index 564e6d11e..5ce0bcebf 100644 --- a/classes/class_control.rst +++ b/classes/class_control.rst @@ -37,11 +37,11 @@ Sets :ref:`mouse_filter` to :ref:`MOUSE_FIL Tutorials --------- -- :doc:`../tutorials/gui/index` +- :doc:`../tutorials/ui/index` - :doc:`../tutorials/2d/custom_drawing_in_2d` -- :doc:`../tutorials/gui/control_node_gallery` +- :doc:`../tutorials/ui/control_node_gallery` - `All GUI Demos `__ diff --git a/classes/class_csharpscript.rst b/classes/class_csharpscript.rst index e3c5f18f8..7017ab7ad 100644 --- a/classes/class_csharpscript.rst +++ b/classes/class_csharpscript.rst @@ -23,7 +23,7 @@ See also :ref:`GodotSharp`. Tutorials --------- -- :doc:`../getting_started/scripting/c_sharp/index` +- :doc:`../tutorials/scripting/c_sharp/index` Methods ------- diff --git a/classes/class_dictionary.rst b/classes/class_dictionary.rst index 75014e03b..98415cc51 100644 --- a/classes/class_dictionary.rst +++ b/classes/class_dictionary.rst @@ -115,7 +115,7 @@ You need to first calculate the dictionary's hash with :ref:`hash`_ in :doc:`../getting_started/scripting/gdscript/gdscript_basics` +- `#dictionary <../tutorials/scripting/gdscript/gdscript_basics.html#dictionary>`_ in :doc:`../tutorials/scripting/gdscript/gdscript_basics` - `3D Voxel Demo `__ diff --git a/classes/class_directory.rst b/classes/class_directory.rst index d1f2734b2..0650e9677 100644 --- a/classes/class_directory.rst +++ b/classes/class_directory.rst @@ -43,7 +43,7 @@ Here is an example on how to iterate through the files of a directory: Tutorials --------- -- :doc:`../getting_started/step_by_step/filesystem` +- :doc:`../tutorials/scripting/filesystem` Methods ------- diff --git a/classes/class_editorscenepostimport.rst b/classes/class_editorscenepostimport.rst index 7cd620752..f1be8b257 100644 --- a/classes/class_editorscenepostimport.rst +++ b/classes/class_editorscenepostimport.rst @@ -42,7 +42,7 @@ The :ref:`post_import` callback Tutorials --------- -- `#custom-script <../getting_started/workflow/assets/importing_scenes.html#custom-script>`_ in :doc:`../getting_started/workflow/assets/importing_scenes` +- `#custom-script <../tutorials/assets_pipeline/importing_scenes.html#custom-script>`_ in :doc:`../tutorials/assets_pipeline/importing_scenes` Methods ------- diff --git a/classes/class_file.rst b/classes/class_file.rst index 79449b9b2..9bb6579b3 100644 --- a/classes/class_file.rst +++ b/classes/class_file.rst @@ -44,7 +44,7 @@ In the example above, the file will be saved in the user data folder as specifie Tutorials --------- -- :doc:`../getting_started/step_by_step/filesystem` +- :doc:`../tutorials/scripting/filesystem` - `3D Voxel Demo `__ diff --git a/classes/class_gdnativelibrary.rst b/classes/class_gdnativelibrary.rst index 18db81610..b0f680b10 100644 --- a/classes/class_gdnativelibrary.rst +++ b/classes/class_gdnativelibrary.rst @@ -21,9 +21,9 @@ A GDNative library can implement :ref:`NativeScript`\ s, glo Tutorials --------- -- :doc:`../tutorials/plugins/gdnative/gdnative-c-example` +_ :doc:`../tutorials/scripting/gdnative/gdnative_c_example` -- :doc:`../tutorials/plugins/gdnative/gdnative-cpp-example` +_ :doc:`../tutorials/scripting/gdnative/gdnative_cpp_example` Properties ---------- diff --git a/classes/class_gdscript.rst b/classes/class_gdscript.rst index 8eefc5e73..2a4066e0b 100644 --- a/classes/class_gdscript.rst +++ b/classes/class_gdscript.rst @@ -23,7 +23,7 @@ A script implemented in the GDScript programming language. The script extends th Tutorials --------- -- :doc:`../getting_started/scripting/gdscript/index` +- :doc:`../tutorials/scripting/gdscript/index` Methods ------- diff --git a/classes/class_image.rst b/classes/class_image.rst index 59cd5eec4..505c355e7 100644 --- a/classes/class_image.rst +++ b/classes/class_image.rst @@ -25,7 +25,7 @@ An ``Image`` cannot be assigned to a ``texture`` property of an object directly Tutorials --------- -- :doc:`../getting_started/workflow/assets/importing_images` +- :doc:`../tutorials/assets_pipeline/importing_images` Properties ---------- diff --git a/classes/class_imagetexture.rst b/classes/class_imagetexture.rst index ee77e9be0..1a7f78276 100644 --- a/classes/class_imagetexture.rst +++ b/classes/class_imagetexture.rst @@ -51,7 +51,7 @@ An ``ImageTexture`` is not meant to be operated from within the editor interface Tutorials --------- -- :doc:`../getting_started/workflow/assets/importing_images` +- :doc:`../tutorials/assets_pipeline/importing_images` Properties ---------- diff --git a/classes/class_javascript.rst b/classes/class_javascript.rst index 5d450f058..8fb2ded13 100644 --- a/classes/class_javascript.rst +++ b/classes/class_javascript.rst @@ -23,7 +23,7 @@ The JavaScript singleton is implemented only in the HTML5 export. It's used to a Tutorials --------- -- `#calling-javascript-from-script <../getting_started/workflow/export/exporting_for_web.html#calling-javascript-from-script>`_ in :doc:`../getting_started/workflow/export/exporting_for_web` +- `#calling-javascript-from-script <../tutorials/export/exporting_for_web.html#calling-javascript-from-script>`_ in :doc:`../tutorials/export/exporting_for_web` Methods ------- diff --git a/classes/class_jnisingleton.rst b/classes/class_jnisingleton.rst index 121802450..94f4bd73e 100644 --- a/classes/class_jnisingleton.rst +++ b/classes/class_jnisingleton.rst @@ -21,7 +21,7 @@ The JNISingleton is implemented only in the Android export. It's used to call me Tutorials --------- -- :doc:`../tutorials/plugins/android/android_plugin` +- :doc:`../tutorials/platform/android/android_plugin` .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` diff --git a/classes/class_multimesh.rst b/classes/class_multimesh.rst index a7a6070c5..56f16eaf5 100644 --- a/classes/class_multimesh.rst +++ b/classes/class_multimesh.rst @@ -27,9 +27,9 @@ Since instances may have any behavior, the AABB used for visibility must be prov Tutorials --------- -- :doc:`../tutorials/3d/vertex_animation/animating_thousands_of_fish` +- :doc:`../tutorials/performance/vertex_animation/animating_thousands_of_fish` -- :doc:`../tutorials/optimization/using_multimesh` +- :doc:`../tutorials/performance/using_multimesh` Properties ---------- diff --git a/classes/class_multimeshinstance.rst b/classes/class_multimeshinstance.rst index c68b6424b..7113c7b97 100644 --- a/classes/class_multimeshinstance.rst +++ b/classes/class_multimeshinstance.rst @@ -23,11 +23,11 @@ This is useful to optimize the rendering of a high amount of instances of a give Tutorials --------- -- :doc:`../tutorials/3d/vertex_animation/animating_thousands_of_fish` +- :doc:`../tutorials/performance/vertex_animation/animating_thousands_of_fish` - :doc:`../tutorials/3d/using_multi_mesh_instance` -- :doc:`../tutorials/optimization/using_multimesh` +- :doc:`../tutorials/performance/using_multimesh` Properties ---------- diff --git a/classes/class_mutex.rst b/classes/class_mutex.rst index 628dcb41a..eedfac8f2 100644 --- a/classes/class_mutex.rst +++ b/classes/class_mutex.rst @@ -21,7 +21,7 @@ A synchronization mutex (mutual exclusion). This is used to synchronize multiple Tutorials --------- -- :doc:`../tutorials/threads/using_multiple_threads` +- :doc:`../tutorials/performance/threads/using_multiple_threads` Methods ------- diff --git a/classes/class_node.rst b/classes/class_node.rst index 376cb7415..1c05525db 100644 --- a/classes/class_node.rst +++ b/classes/class_node.rst @@ -43,7 +43,7 @@ Finally, when a node is freed with :ref:`Object.free` Tutorials --------- -- :doc:`../getting_started/step_by_step/scenes_and_nodes` +- :doc:`../getting_started/step_by_step/nodes_and_scenes` - `All Demos `__ diff --git a/classes/class_object.rst b/classes/class_object.rst index c77e6babf..10435e104 100644 --- a/classes/class_object.rst +++ b/classes/class_object.rst @@ -45,9 +45,9 @@ Objects also receive notifications. Notifications are a simple way to notify the Tutorials --------- -- :doc:`../getting_started/workflow/best_practices/node_alternatives` +- :doc:`../tutorials/best_practices/node_alternatives` -- `#advanced-exports <../getting_started/scripting/gdscript/gdscript_exports.html#advanced-exports>`_ in :doc:`../getting_started/scripting/gdscript/gdscript_exports` +- `#advanced-exports <../tutorials/scripting/gdscript/gdscript_exports.html#advanced-exports>`_ in :doc:`../tutorials/scripting/gdscript/gdscript_exports` Methods ------- diff --git a/classes/class_os.rst b/classes/class_os.rst index 1a451f7b2..ccdcf9ef2 100644 --- a/classes/class_os.rst +++ b/classes/class_os.rst @@ -1686,7 +1686,7 @@ Returns ``true`` if the environment variable with the name ``variable`` exists. - :ref:`bool` **has_feature** **(** :ref:`String` tag_name **)** |const| -Returns ``true`` if the feature for the given feature tag is supported in the currently running instance, depending on the platform, build etc. Can be used to check whether you're currently running a debug build, on a certain platform or arch, etc. Refer to the `Feature Tags `__ documentation for more details. +Returns ``true`` if the feature for the given feature tag is supported in the currently running instance, depending on platform, build etc. Can be used to check whether you're currently running a debug build, on a certain platform or arch, etc. Refer to the `Feature Tags `_ documentation for more details. **Note:** Tag names are case-sensitive. diff --git a/classes/class_particles.rst b/classes/class_particles.rst index 8632b36e4..c0bb63369 100644 --- a/classes/class_particles.rst +++ b/classes/class_particles.rst @@ -27,7 +27,7 @@ Use the ``process_material`` property to add a :ref:`ParticlesMaterial`__ diff --git a/classes/class_reference.rst b/classes/class_reference.rst index 484dd54e1..409667e1f 100644 --- a/classes/class_reference.rst +++ b/classes/class_reference.rst @@ -29,7 +29,7 @@ In the vast majority of use cases, instantiating and using ``Reference``-derived Tutorials --------- -- :doc:`../getting_started/workflow/best_practices/node_alternatives` +- :doc:`../tutorials/best_practices/node_alternatives` Methods ------- diff --git a/classes/class_resource.rst b/classes/class_resource.rst index 24f9366d3..0b8778047 100644 --- a/classes/class_resource.rst +++ b/classes/class_resource.rst @@ -25,9 +25,9 @@ Resource is the base class for all Godot-specific resource types, serving primar Tutorials --------- -- :doc:`../getting_started/step_by_step/resources` +- :doc:`../tutorials/scripting/resources` -- :doc:`../getting_started/workflow/best_practices/node_alternatives` +- :doc:`../tutorials/best_practices/node_alternatives` Properties ---------- diff --git a/classes/class_richtexteffect.rst b/classes/class_richtexteffect.rst index adbcd313a..c3c0d542a 100644 --- a/classes/class_richtexteffect.rst +++ b/classes/class_richtexteffect.rst @@ -30,7 +30,7 @@ A custom effect for use with :ref:`RichTextLabel`. Tutorials --------- -- :doc:`../tutorials/gui/bbcode_in_richtextlabel` +- :doc:`../tutorials/ui/bbcode_in_richtextlabel` - `https://github.com/Eoin-ONeill-Yokai/Godot-Rich-Text-Effect-Test-Project `__ diff --git a/classes/class_richtextlabel.rst b/classes/class_richtextlabel.rst index 2aa39f374..d0a5e6fbc 100644 --- a/classes/class_richtextlabel.rst +++ b/classes/class_richtextlabel.rst @@ -31,7 +31,7 @@ Rich text can contain custom text, fonts, images and some basic formatting. The Tutorials --------- -- :doc:`../tutorials/gui/bbcode_in_richtextlabel` +- :doc:`../tutorials/ui/bbcode_in_richtextlabel` - `GUI Rich Text/BBcode Demo `__ diff --git a/classes/class_scenetree.rst b/classes/class_scenetree.rst index 334faa2dc..4da4afdd6 100644 --- a/classes/class_scenetree.rst +++ b/classes/class_scenetree.rst @@ -25,9 +25,9 @@ You can also use the ``SceneTree`` to organize your nodes into groups: every nod Tutorials --------- -- :doc:`../getting_started/step_by_step/scene_tree` +- :doc:`../tutorials/scripting/scene_tree` -- :doc:`../tutorials/viewports/multiple_resolutions` +- :doc:`../tutorials/rendering/multiple_resolutions` Properties ---------- diff --git a/classes/class_script.rst b/classes/class_script.rst index 459c0823c..f162f21f7 100644 --- a/classes/class_script.rst +++ b/classes/class_script.rst @@ -25,7 +25,7 @@ The ``new`` method of a script subclass creates a new instance. :ref:`Object.set Tutorials --------- -- :doc:`../getting_started/step_by_step/scripting` +- :doc:`../getting_started/step_by_step/scripting_first_script` Properties ---------- diff --git a/classes/class_semaphore.rst b/classes/class_semaphore.rst index 2c87c6b06..c5a124e3f 100644 --- a/classes/class_semaphore.rst +++ b/classes/class_semaphore.rst @@ -21,7 +21,7 @@ A synchronization semaphore which can be used to synchronize multiple :ref:`Thre Tutorials --------- -- :doc:`../tutorials/threads/using_multiple_threads` +- :doc:`../tutorials/performance/threads/using_multiple_threads` Methods ------- diff --git a/classes/class_shader.rst b/classes/class_shader.rst index c56274c49..1610a91d0 100644 --- a/classes/class_shader.rst +++ b/classes/class_shader.rst @@ -23,9 +23,9 @@ This class allows you to define a custom shader program that can be used by a :r Tutorials --------- -- :doc:`../tutorials/shading/index` +- :doc:`../tutorials/shaders/index` -- :doc:`../tutorials/shading/your_first_shader/what_are_shaders` +- :ref:`doc_introduction_to_shaders` Properties ---------- diff --git a/classes/class_shadermaterial.rst b/classes/class_shadermaterial.rst index 5ab09297f..d5d109a53 100644 --- a/classes/class_shadermaterial.rst +++ b/classes/class_shadermaterial.rst @@ -23,7 +23,7 @@ A material that uses a custom :ref:`Shader` program to render eith Tutorials --------- -- :doc:`../tutorials/shading/index` +- :doc:`../tutorials/shaders/index` Properties ---------- diff --git a/classes/class_string.rst b/classes/class_string.rst index 5a2837602..b10bb5c63 100644 --- a/classes/class_string.rst +++ b/classes/class_string.rst @@ -19,7 +19,7 @@ This is the built-in string class (and the one used by GDScript). It supports Un Tutorials --------- -- :doc:`../getting_started/scripting/gdscript/gdscript_format_string` +- :doc:`../tutorials/scripting/gdscript/gdscript_format_string` Methods ------- diff --git a/classes/class_theme.rst b/classes/class_theme.rst index 496ab2862..046bd98e5 100644 --- a/classes/class_theme.rst +++ b/classes/class_theme.rst @@ -23,7 +23,7 @@ Theme resources can alternatively be loaded by writing them in a ``.theme`` file Tutorials --------- -- :doc:`../tutorials/gui/gui_skinning` +- :doc:`../tutorials/ui/gui_skinning` Properties ---------- diff --git a/classes/class_thread.rst b/classes/class_thread.rst index 63d10aab2..216e3f1ad 100644 --- a/classes/class_thread.rst +++ b/classes/class_thread.rst @@ -23,9 +23,9 @@ A unit of execution in a process. Can run methods on :ref:`Object` Tutorials --------- -- :doc:`../tutorials/threads/using_multiple_threads` +- :doc:`../tutorials/performance/threads/using_multiple_threads` -- :doc:`../tutorials/threads/thread_safe_apis` +- :doc:`../tutorials/performance/threads/thread_safe_apis` - `3D Voxel Demo `__ diff --git a/classes/class_viewport.rst b/classes/class_viewport.rst index b7e47f3b9..e74867cab 100644 --- a/classes/class_viewport.rst +++ b/classes/class_viewport.rst @@ -33,7 +33,7 @@ Tutorials - :doc:`../tutorials/2d/2d_transforms` -- :doc:`../tutorials/viewports/index` +- :doc:`../tutorials/rendering/viewports` - `GUI in 3D Demo `__ diff --git a/classes/class_visualscript.rst b/classes/class_visualscript.rst index 5be86dbb8..c5c9fb7a1 100644 --- a/classes/class_visualscript.rst +++ b/classes/class_visualscript.rst @@ -25,7 +25,7 @@ You are most likely to use this class via the Visual Script editor or when writi Tutorials --------- -- :doc:`../getting_started/scripting/visual_script/index` +- :doc:`../tutorials/scripting/visual_script/index` Methods ------- diff --git a/classes/class_visualserver.rst b/classes/class_visualserver.rst index ee3c43716..649ae04ad 100644 --- a/classes/class_visualserver.rst +++ b/classes/class_visualserver.rst @@ -37,7 +37,7 @@ In 2D, all visible objects are some form of canvas item. In order to be visible, Tutorials --------- -- :doc:`../tutorials/optimization/using_servers` +- :doc:`../tutorials/performance/using_servers` Properties ---------- diff --git a/classes/class_visualshadernode.rst b/classes/class_visualshadernode.rst index 7090639ed..d018559a4 100644 --- a/classes/class_visualshadernode.rst +++ b/classes/class_visualshadernode.rst @@ -23,7 +23,7 @@ Visual shader graphs consist of various nodes. Each node in the graph is a separ Tutorials --------- -- :doc:`../tutorials/shading/visual_shaders` +- :doc:`../tutorials/shaders/visual_shaders` Properties ---------- diff --git a/classes/class_visualshadernodeinput.rst b/classes/class_visualshadernodeinput.rst index a23a80432..6452a5133 100644 --- a/classes/class_visualshadernodeinput.rst +++ b/classes/class_visualshadernodeinput.rst @@ -21,7 +21,7 @@ Gives access to input variables (built-ins) available for the shader. See the sh Tutorials --------- -- :doc:`../tutorials/shading/shading_reference/index` +- :doc:`../tutorials/shaders/shader_reference/index` Properties ---------- diff --git a/community/asset_library/img/assetlib_asset.png b/community/asset_library/img/assetlib_asset.png new file mode 100644 index 000000000..10319e45c Binary files /dev/null and b/community/asset_library/img/assetlib_asset.png differ diff --git a/community/asset_library/img/assetlib_editor.png b/community/asset_library/img/assetlib_editor.png new file mode 100644 index 000000000..c7c5776a2 Binary files /dev/null and b/community/asset_library/img/assetlib_editor.png differ diff --git a/community/asset_library/img/assetlib_editor_asset.png b/community/asset_library/img/assetlib_editor_asset.png new file mode 100644 index 000000000..16ebd9b1d Binary files /dev/null and b/community/asset_library/img/assetlib_editor_asset.png differ diff --git a/community/asset_library/img/assetlib_editor_download.png b/community/asset_library/img/assetlib_editor_download.png new file mode 100644 index 000000000..7b8dc79cd Binary files /dev/null and b/community/asset_library/img/assetlib_editor_download.png differ diff --git a/community/asset_library/img/assetlib_editor_installer.png b/community/asset_library/img/assetlib_editor_installer.png new file mode 100644 index 000000000..c6dcf770f Binary files /dev/null and b/community/asset_library/img/assetlib_editor_installer.png differ diff --git a/community/asset_library/img/assetlib_editor_installer_error.png b/community/asset_library/img/assetlib_editor_installer_error.png new file mode 100644 index 000000000..b1080f4a2 Binary files /dev/null and b/community/asset_library/img/assetlib_editor_installer_error.png differ diff --git a/community/asset_library/img/assetlib_editor_installer_success.png b/community/asset_library/img/assetlib_editor_installer_success.png new file mode 100644 index 000000000..a673cbad1 Binary files /dev/null and b/community/asset_library/img/assetlib_editor_installer_success.png differ diff --git a/community/asset_library/img/assetlib_editor_projects.png b/community/asset_library/img/assetlib_editor_projects.png new file mode 100644 index 000000000..af9575457 Binary files /dev/null and b/community/asset_library/img/assetlib_editor_projects.png differ diff --git a/community/asset_library/img/assetlib_editor_workspace.png b/community/asset_library/img/assetlib_editor_workspace.png new file mode 100644 index 000000000..b56976769 Binary files /dev/null and b/community/asset_library/img/assetlib_editor_workspace.png differ diff --git a/community/asset_library/img/assetlib_login.png b/community/asset_library/img/assetlib_login.png new file mode 100644 index 000000000..67a09a7f9 Binary files /dev/null and b/community/asset_library/img/assetlib_login.png differ diff --git a/community/asset_library/img/assetlib_login_header.png b/community/asset_library/img/assetlib_login_header.png new file mode 100644 index 000000000..eeaf8f9ab Binary files /dev/null and b/community/asset_library/img/assetlib_login_header.png differ diff --git a/community/asset_library/img/assetlib_register-login.png b/community/asset_library/img/assetlib_register-login.png new file mode 100644 index 000000000..c5dffeed4 Binary files /dev/null and b/community/asset_library/img/assetlib_register-login.png differ diff --git a/community/asset_library/img/assetlib_register.png b/community/asset_library/img/assetlib_register.png new file mode 100644 index 000000000..370bffb5e Binary files /dev/null and b/community/asset_library/img/assetlib_register.png differ diff --git a/community/asset_library/img/assetlib_search.png b/community/asset_library/img/assetlib_search.png new file mode 100644 index 000000000..87b8c8f25 Binary files /dev/null and b/community/asset_library/img/assetlib_search.png differ diff --git a/community/asset_library/img/assetlib_submit.png b/community/asset_library/img/assetlib_submit.png new file mode 100644 index 000000000..587e0314c Binary files /dev/null and b/community/asset_library/img/assetlib_submit.png differ diff --git a/community/asset_library/img/assetlib_website.png b/community/asset_library/img/assetlib_website.png new file mode 100644 index 000000000..ec6cf5cd5 Binary files /dev/null and b/community/asset_library/img/assetlib_website.png differ diff --git a/tutorials/assetlib/index.rst b/community/asset_library/index.rst similarity index 86% rename from tutorials/assetlib/index.rst rename to community/asset_library/index.rst index a2479b5eb..3edb5fe83 100644 --- a/tutorials/assetlib/index.rst +++ b/community/asset_library/index.rst @@ -7,4 +7,5 @@ Asset Library what_is_assetlib using_assetlib + submitting_to_assetlib uploading_to_assetlib diff --git a/community/asset_library/submitting_to_assetlib.rst b/community/asset_library/submitting_to_assetlib.rst new file mode 100644 index 000000000..940f3c7cc --- /dev/null +++ b/community/asset_library/submitting_to_assetlib.rst @@ -0,0 +1,210 @@ +.. _doc_submitting_to_assetlib: + +Submitting to the Asset Library +=============================== + +Introduction +------------ + +This tutorial aims to serve as a guide on how you can submit your own assets +to the Godot Asset Library and share them with the Godot community. + +As mentioned in the :ref:`doc_using_assetlib` document, in order to be able to +submit assets to the AssetLib, you need to have a registered account, and be +logged in. + +Submission guidelines +--------------------- + +Before submitting your asset, please ensure it follows all of the +requirements, and also consider following the recommendations. + +Requirements +~~~~~~~~~~~~ + +Generally speaking, most assets people submit to the asset library +are accepted. However, in order for your asset to be accepted, there +are a few requirements your asset needs to meet to be approved. + +* The asset must **work**. If the asset doesn't run or otherwise doesn't + work in the specified Godot version, then it will be rejected. + +* The asset must have a proper **.gitignore** file. It's important to + keep redundant data out of the repository. + `Here's a template. `_ + +* No **submodules**, or any submodules must be non-essential. GitHub + does not include submodules in the downloaded ZIP file, so if the + asset needs the contents of the submodule, your asset won't work. + +* The **license** needs to be correct. The license listed on the asset + library must match the license in the repository. The repo MUST + have a license file, called either "LICENSE" or "LICENSE.md". + This file must contain the license text itself and a copyright + statement that includes the year(s) and copyright holder. + +* Use proper **English** for the name and description of your asset. + This includes using correct capitalization, and using full + sentences in the description. You can also include other languages, + but there should at least be an English version. + +* The icon link must be a **direct link**. For icons hosted on GitHub, the + link must start with "raw.githubusercontent.com", not "github.com". + +Recommendations +~~~~~~~~~~~~~~~ + +These things are not required for your asset to be approved, but +if you follow these recommendations, you can help make the asset +library a better place for all users. + +* Fix or suppress all script **warnings**. The warning system is there to + help identify issues with your code, but people using your asset + don't need to see them. + +* Make your code conform to the official **style guides**. Having a + consistent style helps other people read your code, and it also helps + if other people wish to contribute to your asset. See: the + :ref:`doc_gdscript_styleguide` or the :ref:`doc_c_sharp_styleguide`. + +* If you have screenshots in your repo, place them in their own subfolder + and add an empty **.gdignore** file in the same folder (note: **gd**, not **git**). + This prevents Godot from importing your screenshots. + On Windows, open a command prompt in the project folder and run + ``type nul > .gdignore`` to create a file whose name starts with a period. + +* If your asset is a library for working with other files, + consider including **example files** in the asset. + +* Consider adding a **.gitattributes** file to your repo. This file allows + giving extra instructions to Git, such as specifying line endings and listing + files not required for your asset to function with the ``export-ignore`` + directive. This directive removes such files from the resulting ZIP file + and prevents them from being downloaded by the asset library users. + For a typical plugin **.gitattributes** may look like this: + + .. code-block:: none + + # Normalize EOL for all files that Git considers text files. + * text=auto eol=lf + + # Ignore some files when exporting to a ZIP. + /.gitattributes export-ignore + /.gitignore export-ignore + /LICENSE export-ignore + /LICENSE.md export-ignore + /README.md export-ignore + /project.godot export-ignore + /icon.png export-ignore + /icon.svg export-ignore + + Other types of assets may require a different configuration (e.g. + a project template requires **project.godot**). + +* If you are submitting a plugin, add a **copy** of your license and readme + to the plugin folder itself. This is the folder that users are guaranteed to + keep with their project, so a copy ensures they always have those files handy + (and helps them fulfill your licensing terms). + +* The **icon** should be a square, its aspect ratio should be 1:1. It should + also ideally have a minimum resolution of 64x64 pixels. + +* While the asset library allows more than just GitHub, consider + hosting your asset's source code on **GitHub**. Other services may not + work reliably, and a lack of familiarity can be a barrier to contributors. + +Submitting +---------- + +Once you are logged in, you will be able to head over to the "Submit Assets" page +of the AssetLib, which will look like this: + +|image0| + +While it may look like a lot (and there is more as you scroll down), each field is +described in terms of what you should put in. We will nonetheless go over what +is required in the submission form here as well. + +* **Asset Name**: + The name of your asset. Should be a unique, descriptive title of + what your asset is. +* **Category**: + The category that your asset belongs to, and will be shown in + search results. The category is split into **Addons** and **Projects**. + In-editor, assets of the Project type (Templates, Demos, Projects) only show + up when viewing the AssetLib from the Project Manager, while assets of the + Addon type will only be visible from inside a project. +* **Godot version**: + The version of the engine that the asset works with. + Currently, it's not possible to have a single asset entry contain downloads for + multiple engine versions, so you may need to re-submit the asset multiple times, + with an entry for each Godot version it supports. This is particularly important + when dealing with major versions of the engine, such as Godot 2.x and Godot 3.x. +* **Version**: + The version number of the asset. While you are free to choose + and use any versioning scheme that you like, you may want to look into + something such as `SemVer `_ if you want your asset's + versioning scheme to be clear and consistent. Note that there is also an + internal version number, incremented every time the asset download URL is + changed or updated. +* **Repository host**: + Assets uploaded to the AssetLib are not hosted on it + directly. Instead, they point to repositories hosted on third-party Git providers, + such as GitHub, GitLab or Bitbucket. This is where you choose which provider + your asset uses, so the site can compute the final download link. +* **Repository URL**: + The URL to your asset's files/webpage. This will vary + based on your choice of provider, but it should look similar to `https://github.com//`. +* **Issues URL**: + The URL to your asset's issue tracker. Again, this will differ + from repository host to repository host, but will likely look similar to + `https://github.com///issues`. You may leave this field empty + if you use your provider's issue tracker, and it's part of the same repository. +* **Download Commit**: + The commit of the asset. For example, + `b1d3172f89b86e52465a74f63a74ac84c491d3e1`. The site computes + the actual download URL from this. +* **Icon URL**: + The URL to your asset's icon (which will be used as a thumbnail + in the AssetLib search results and on the asset's page). Should be an image + in either the PNG or JPG format. +* **License**: + The license under which you are distributing the asset. The list + includes a variety of free and open-source software licenses, such as GPL + (v2 and v3), MIT, BSD and Boost Software License. You can visit `OpenSource.org `_ + for a detailed description of each of the listed licenses. +* **Description**: + Finally, you can use the Description field for a textual + overview of your asset, its features and behavior, a changelog, et cetera. In the + future, formatting with Markdown will be supported, but currently, your only + option is plain text. + +You may also include up to three video and/or image previews, which will be shown +at the bottom of the asset page. Use the "Enable" checkbox on each of the preview +submission boxes to enable them. + +* **Type**: + Either an image, or a video. +* **Image/YouTube URL**: + Either a link to the image, or to a video, hosted on YouTube. +* **Thumbnail URL**: + A URL to an image that will be used as a thumbnail for the + preview. This option will be removed eventually, and thumbnails will be automatically + computed instead. + +Once you are done, press "Submit". Your asset will be entered into the review queue. +You can check all assets currently pending a review `here `_ . +The approval process is manual and may take up to a few days for your asset to be accepted (or rejected), so please +be patient! + +.. note:: + + You may have some luck accelerating the approval process by messaging the + moderators and AssetLib reviewers on the `Contributors Chat `_, + or the official Discord server. + +You will be informed when your asset is reviewed. If it was rejected, +you will be told why that may have been, and you will be able to submit it again +with the appropriate changes. + +.. |image0| image:: img/assetlib_submit.png diff --git a/tutorials/assetlib/uploading_to_assetlib.rst b/community/asset_library/uploading_to_assetlib.rst similarity index 100% rename from tutorials/assetlib/uploading_to_assetlib.rst rename to community/asset_library/uploading_to_assetlib.rst diff --git a/tutorials/assetlib/using_assetlib.rst b/community/asset_library/using_assetlib.rst similarity index 98% rename from tutorials/assetlib/using_assetlib.rst rename to community/asset_library/using_assetlib.rst index 312ab3d2c..3ca1a6e31 100644 --- a/tutorials/assetlib/using_assetlib.rst +++ b/community/asset_library/using_assetlib.rst @@ -99,7 +99,7 @@ new functions: |image6| You can learn how to submit assets to the Library, and what the asset submission -guidelines are, in the next part of this tutorial, :ref:`doc_uploading_to_assetlib`. +guidelines are, in the next part of this tutorial, :ref:`doc_submitting_to_assetlib`. In the editor ------------- diff --git a/tutorials/assetlib/what_is_assetlib.rst b/community/asset_library/what_is_assetlib.rst similarity index 100% rename from tutorials/assetlib/what_is_assetlib.rst rename to community/asset_library/what_is_assetlib.rst diff --git a/community/channels.rst b/community/channels.rst index 79e4acda9..56035bea6 100644 --- a/community/channels.rst +++ b/community/channels.rst @@ -14,16 +14,25 @@ Q&A - `Official Godot Questions & Answers `_ +Rocket.Chat +----------- + +- `Godot Contributors Chat `_ + IRC on Freenode --------------- +.. note:: + + As of January 2021, core developer chat has moved to the Godot Contributors Chat platform listed above. + - `General: #godotengine `_ - `Engine development: #godotengine-devel `_ - `Documentation: #godotengine-doc `_ - `Pull request meetings: #godotengine-meeting `_ - `GDNative: #godotengine-gdnative `_ - `Website and public relations: #godotengine-atelier `_ -- `IRC logs `_ +- `IRC logs `_ Other chats ----------- diff --git a/community/contributing/best_practices_for_engine_contributors.rst b/community/contributing/best_practices_for_engine_contributors.rst index c5403c98d..204bf832e 100644 --- a/community/contributing/best_practices_for_engine_contributors.rst +++ b/community/contributing/best_practices_for_engine_contributors.rst @@ -36,7 +36,7 @@ Best Practices Many contributors are extremely creative and just enjoy the process of designing abstract data structures, creating nice user interfaces, or simply love programming. Whatever the case may be, they come up with cool ideas, which may -not be actually solving any actual problems. +or may not be solving any real problems. .. image:: img/best_practices1.png @@ -90,7 +90,7 @@ to work around it. This difficulty can be expressed as: If the problem is *too complex* for most users to solve, the software must offer a ready-made solution for it. Likewise, if the problem is easy for the user to -workaround, offering such a solution is unnecessary and it's up to the user to +work around, offering such a solution is unnecessary and it's up to the user to do it. The exception, however, is when the user stumbles into this problem *frequently @@ -104,9 +104,9 @@ This is why discussing with other developers (next point) is always advised. #4: The solution must be discussed with others ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -It is often the case that, when users stumble upon problems, they are only -immersed in their own project, so they will naturally try to solve the problem -from their own perspective, thinking only about their use case. +It is often the case that when users stumble upon problems, they are only +immersed in their project, so they will naturally try to solve the problem +from their perspective, thinking only about their use case. Because of this, user proposed solutions don't always contemplate other use cases that developers are often aware of, so they are often biased towards their @@ -148,7 +148,7 @@ problems (as described in #2) also make their appearance on stage. .. image:: img/best_practices5.png The main problem is that, in reality, it rarely works this way. Most of the -time, just writing an individual solution to each problem results in code that +time, writing an individual solution to each problem results in code that is simpler and more maintainable. Additionally, solutions that target individual problems are better for the @@ -157,7 +157,7 @@ to learn and remember a more complex system they will only need for simple tasks. Big and flexible solutions also have an additional drawback which is that, over -time, they are rarely flexible enough for all users, which keep requesting more +time, they are rarely flexible enough for all users, who keep requesting more functions added (and making the API and codebase more and more complex). #6: Cater to common use cases, leave the door open for the rare ones @@ -225,7 +225,7 @@ but this path is always the advised one. Not every problem has a simple solution and, many times, the right choice is to use a third party library to solve the problem. -As Godot requires to be shipped in a large amount of platforms, we just can't +As Godot requires to be shipped in a large amount of platforms, we can't link libraries dynamically. Instead, we bundle them in our source tree. .. image:: img/best_practices8.png diff --git a/community/contributing/bug_triage_guidelines.rst b/community/contributing/bug_triage_guidelines.rst index 4cee9097f..def4c88ea 100644 --- a/community/contributing/bug_triage_guidelines.rst +++ b/community/contributing/bug_triage_guidelines.rst @@ -4,8 +4,9 @@ Bug triage guidelines ===================== This page describes the typical workflow of the bug triage team aka -bugsquad when handling issues and pull requests on Godot's `GitHub `_ -repository. It is bound to evolve together with the bugsquad, so do not +bugsquad when handling issues and pull requests on Godot's +`GitHub repository `__. +It is bound to evolve together with the bugsquad, so do not hesitate to propose modifications to the following guidelines. Issues management @@ -25,7 +26,7 @@ contributors are welcome to take on any issue, if relevant after mentioning it on the issue ticket and/or discussing the best way to resolve it with other developers. -For the time being we do not use the project dashboard feature either. +For the time being, we do not use the project dashboard feature either. As far as possible, we try to assign labels (and milestones, when relevant) to both issues and pull requests. @@ -39,7 +40,13 @@ The following labels are currently defined in the Godot repository: - *Archived*: either a duplicate of another issue, or invalid. Such an issue would also be closed. +- *Breaks compat*: describes something that can only be fixed by breaking + compatibility with existing projects. - *Bug*: describes something that is not working properly. +- *Cherrypick*: describes something that can be backported to a stable branch + after being merged in the ``master`` branch. +- *Crash:* describes a bug that causes the engine to crash. + This label is only used for "hard" crashes, not freezes. - *Confirmed*: has been confirmed by at least one other contributor than the bug reporter (typically for *Bug* reports). The purpose of this label is to let developers know which issues are @@ -58,11 +65,17 @@ The following labels are currently defined in the Godot repository: - *Enhancement*: describes a proposed enhancement to an existing functionality. - *Feature proposal*: describes a wish for a new feature to be - implemented. + implemented. Note that the main Godot repository no longer accepts + feature requests. Please use + `godot-proposals `__ instead. +- *For PR meeting*: the issue needs to be discussed in a pull request meeting. + These meetings are public and are held on the `Godot Contributors Chat `_. - *Junior job*: the issue is *assumed* to be an easy one to fix, which makes it a great fit for junior contributors who need to become familiar with the code base. -- *Needs rebase*: the issue need a Git rebase to be merged. +- *High priority:* the issue is particularly important as it can + prevent people from releasing their projects or cause data loss. +- *Needs work*: the pull request needs additional work before it can be merged. - *Needs testing*: the issue/pull request could not be completely tested and thus need further testing. This can mean that it needs to be tested on different hardware/software configurations or even that the steps to @@ -97,19 +110,27 @@ feature request, or one that is not precise enough to be worked on. - *Audio*: relates to the audio features (low and high level). - *Buildsystem*: relates to building issues, either linked to the SCons buildsystem or to compiler peculiarities. +- *Codestyle*: relates to the programming style used within the codebase. - *Core*: anything related to the core engine. It might be further split later on as it's a pretty big topic. -- *Drivers*: relates to issues with the drivers used by the engine. - *Editor*: relates to issues in the editor (mainly UI). - *GDNative*: relates to the GDNative module. - *GDScript*: relates to GDScript. +- *GUI*: relates to GUI (Control) nodes. +- *Import*: relates to the resource import system. +- *Input*: relates to input system. - *Mono*: relates to the C# / Mono bindings. +- *Navigation*: relates to the navigation system (including A* and navmeshes). - *Network*: relates to networking. - *Physics*: relates to the physics engine (2D/3D). - *Plugin*: relates to problems encountered while writing plugins. -- *Porting*: relates to some specific platforms. +- *Porting*: relates to some specific platforms or exporting projects. - *Rendering*: relates to the 2D and 3D rendering engines. -- *VisualScript*: relates to issues with the visual scripting language. +- *Shaders*: relates to the Godot shader language or visual shaders. +- *Tests*: relates to unit tests. +- *Thirdparty*: relates to third-party libraries used in Godot. +- *VisualScript*: relates to issues with the visual scripting language (*not* visual shaders). +- *XR*: relates to Augmented Reality or Virtual Reality. Issues would typically correspond to only one topic, though it's not unthinkable to see issues that fit two bills. The general idea is that @@ -125,17 +146,45 @@ If one of the platform labels is used, it is then exclusive and the previous assumption doesn't stand anymore (so if it's a bug on e.g. Android and Linux exclusively, select those two platforms). +Documentation labels +~~~~~~~~~~~~~~~~~~~~ + +In the `documentation repository `__, we +use the following labels: + +- *Bug*: Incorrect information in an existing page. Not to be used for + *missing* information. +- *Class reference*: the issue is about the class reference, not a documentation page. +- *Discussion*: the issue is not consensual and needs further + discussion to define what exactly should be done to address the + topic. +- *Enhancememnt*: new information to be added in an existing page. +- *New page*: a new page to be created. +- *Hero wanted!*: contributions for issues with these labels + are especially welcome. Note that this **doesn't** mean you can't work + on issues without these labels. +- *Organization*: The issue involves moving pages around or reorganizing content. +- *Redirect*: a redirection needs to be created in the Read the Docs backend. + Only administrators can do this. +- *Salvageable*: the pull request can't be merged due to design issues or + merge conflicts and its author is not active anymore. However, it can still + be picked up by an external contributor to bring it to a mergeable state. + To do so, you need to open a new pull request based on the original pull request. +- *Topic:Mono*: the issue is about C# support in Godot. +- *Topic:Website*: the issue relates to the Sphinx/Read the Docs frontend or backend, + not the documentation contents. + Milestones ~~~~~~~~~~ -`Milestones `_ correspond to planned future versions of Godot for which -there is an existing roadmap. Issues that fit in the said roadmap should -be filed under the corresponding milestone; if they don't correspond to -any current roadmap, they should be left without milestone. As a rule of -thumb, an issue corresponds to a given milestone if it concerns a feature -that is new in the milestone, or a critical bug that can't be accepted in any -future stable release, or anything that Juan wants to work on right now. -:) +`Milestones `_ correspond to +planned future versions of Godot for which there is an existing roadmap. Issues +that fit in the said roadmap should be filed under the corresponding milestone; +if they don't correspond to any current roadmap, they should be left without +milestone. As a rule of thumb, an issue corresponds to a given milestone if it +concerns a feature that is new in the milestone, or a critical bug that can't be +accepted in any future stable release, or anything that Juan wants to work on +right now. :) Contributors are free to pick issues regardless of their assigned milestone; if a fix is proposed for a bug that was not deemed urgent and thus without diff --git a/community/contributing/building_the_manual.rst b/community/contributing/building_the_manual.rst index 50d00ca86..a5e016448 100644 --- a/community/contributing/building_the_manual.rst +++ b/community/contributing/building_the_manual.rst @@ -21,7 +21,7 @@ install all these tools. It comes pre-installed with `Python `__. Ensure that you install and use Python 3. Here are the commands to clone the repository and then install all requirements. -.. note:: You may need to write ``python3 -m pip`` (Unix) or ``py -m pip`` (Windows) instead of ``pip3``. +.. note:: You may need to write ``python3 -m pip`` (Unix) or ``py -m pip`` (Windows) instead of ``pip3``. If both approaches fail, `check that you have pip3 installed `__. .. code:: sh diff --git a/community/contributing/class_reference_writing_guidelines.rst b/community/contributing/class_reference_writing_guidelines.rst new file mode 100644 index 000000000..149256f19 --- /dev/null +++ b/community/contributing/class_reference_writing_guidelines.rst @@ -0,0 +1,254 @@ +.. _doc_class_reference_writing_guidelines: + +Class reference writing guidelines +================================== + +This page explains how to write the class reference. You will learn where to +write new descriptions for the classes, methods, and properties for Godot's +built-in node types. + +.. seealso:: + + To learn to submit your changes to the Godot project using the Git version + control system, see :ref:`doc_updating_the_class_reference`. + +The reference for each class is contained in an XML file like the one below: + +.. code-block:: xml + + + + A 2D game object, inherited by all 2D-related nodes. Has a position, rotation, scale, and Z index. + + + A 2D game object, with a transform (position, rotation, and scale). All 2D nodes, including physics objects and sprites, inherit from Node2D. Use Node2D as a parent node to move, scale and rotate children in a 2D project. Also gives control of the node's render order. + + + https://docs.godotengine.org/en/latest/tutorials/2d/custom_drawing_in_2d.html + https://github.com/godotengine/godot-demo-projects/tree/master/2d + + + + + + + + + Multiplies the current scale by the [code]ratio[/code] vector. + + + [...] + + + + + + + Translates the node by the given [code]offset[/code] in local coordinates. + + + + + + Global position. + + [...] + + Z index. Controls the order in which the nodes render. A node with a higher Z index will display in front of others. + + + + + + + +It starts with brief and long descriptions. In the generated docs, the brief +description is always at the top of the page, while the long description lies +below the list of methods, variables, and constants. You can find methods, +member variables, constants, and signals in separate XML nodes. + +For each, you want to learn how they work in Godot's source code. Then, fill +their documentation by completing or improving the text in these tags: + +- `` +- `` +- `` +- `` (in its `` tag; return types and arguments don't take separate + documentation strings) +- `` +- `` (in its `` tag; arguments don't take separate documentation strings) +- `` + +Write in a clear and simple language. Always follow the :ref:`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. + +.. _doc_class_reference_writing_guidelines_editing_xml: + +How to edit class XML +--------------------- + +Edit the file for your chosen class in ``doc/classes/`` to update the class +reference. The folder contains an XML file for each class. The XML lists the +constants and methods you will find in the class reference. Godot generates and +updates the XML automatically. + +.. note:: For some modules in the engine's source code, you'll find the XML + files in the ``modules//doc_classes/`` directory instead. + +Edit it using your favorite text editor. If you use a code editor, make sure +that it doesn't change the indent style: you should use tabs for the XML and +four spaces inside BBCode-style blocks. More on that below. + +To check that the modifications you've made are correct in the generated +documentation, navigate to the ``doc/`` folder and run the command ``make rst``. +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 +guide `. + +We recommend using a code editor that supports XML files like Vim, Atom, Visual Studio Code, +Notepad++, or another to comfortably edit the file. You can also use their +search feature to find classes and properties quickly. + +.. _doc_class_reference_writing_guidelines_bbcode: + +Improve formatting with BBCode style tags +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Godot's class reference supports BBCode-like tags. They add nice formatting to +the text. Here's the list of available tags: + ++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ +| Tag | Effect | Usage | Result | ++============================+======================================+===================================+===================================================+ +| [Class] | Link a class | Move the [Sprite2D]. | Move the :ref:`class_Sprite`. | ++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ +| [method methodname] | Link to a method in this class | Call [method hide]. | Call :ref:`hide `. | ++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ +| [method Class.methodname] | Link to another class's method | Call [method Node3D.hide]. | Call :ref:`hide `. | ++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ +| [member membername] | Link to a member in this class | Get [member scale]. | Get :ref:`scale `. | ++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ +| [member Class.membername] | Link to another class's member | Get [member Node2D.scale]. | Get :ref:`scale `. | ++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ +| [signal signalname] | Link to a signal in this class | Emit [signal renamed]. | Emit :ref:`renamed `. | ++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ +| [signal Class.signalname] | Link to another class's signal | Emit [signal Node.renamed]. | Emit :ref:`renamed `. | ++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ +| [b] [/b] | Bold | Some [b]bold[/b] text. | Some **bold** text. | ++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ +| [i] [/i] | Italic | Some [i]italic[/i] text. | Some *italic* text. | ++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ +| [code] [/code] | Monospace | Some [code]monospace[/code] text. | Some ``monospace`` text. | ++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ +| [kbd] [/kbd] | Keyboard/mouse shortcut | Some [kbd]Ctrl + C[/kbd] key. | Some :kbd:`Ctrl + C` key. | ++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ +| [codeblock] [/codeblock] | Multiline preformatted block | *See below.* | *See below.* | ++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ +| [codeblocks] [/codeblocks] | [codeblock] for multiple languages | *See below.* | *See below.* | ++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ +| [gdscript] [/gdscript] | GDScript codeblock tab in codeblocks | *See below.* | *See below.* | ++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ +| [csharp] [/csharp] | C# codeblock tab in codeblocks | *See below.* | *See below.* | ++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ + +Use ``[codeblock]`` for pre-formatted code blocks. Inside ``[codeblock]``, +always use **four spaces** for indentation. The parser will delete tabs. For +example: + +.. code-block:: none + + [codeblock] + func _ready(): + var sprite = get_node("Sprite2D") + print(sprite.get_pos()) + [/codeblock] + +Will display as: + +.. code-block:: gdscript + + func _ready(): + var sprite = get_node("Sprite2D") + print(sprite.get_pos()) + +If you need to have different code version in GDScript and C#, use +``[codeblocks]`` instead. If you use ``[codeblocks]``, you also need to have at +least one of the language-specific tags, ``[gdscript]`` and ``[csharp]``. + +Always write GDScript code examples first! You can use this `experimental code +translation tool `_ to speed up your +workflow. + +.. code-block:: none + + [codeblocks] + [gdscript] + func _ready(): + var sprite = get_node("Sprite2D") + print(sprite.get_pos()) + [/gdscript] + [csharp] + public override void _Ready() + { + var sprite = GetNode("Sprite2D"); + GD.Print(sprite.GetPos()); + } + [/csharp] + [/codeblocks] + +The above will display as: + +.. tabs:: + .. code-tab:: gdscript GDScript + + func _ready(): + var sprite = get_node("Sprite2D") + print(sprite.get_pos()) + + .. code-tab:: csharp + + public override void _Ready() + { + var sprite = GetNode("Sprite2D"); + GD.Print(sprite.GetPos()); + } + +To denote important information, add a paragraph starting with "[b]Note:[/b]" at +the end of the description: + +.. code-block:: none + + [b]Note:[/b] Only available when using the Vulkan renderer. + +To denote crucial information that could cause security issues or loss of data +if not followed carefully, add a paragraph starting with "[b]Warning:[/b]" at +the end of the description: + +.. code-block:: none + + [b]Warning:[/b] If this property is set to [code]true[/code], it allows clients to execute arbitrary code on the server. + +For deprecated properties, add a paragraph starting with "[i]Deprecated.[/i]". +Notice the use of italics instead of bold: + +.. code-block:: none + + [i]Deprecated.[/i] This property has been replaced by [member other_property]. + +In all the paragraphs described above, make sure the punctuation is part of the +BBCode tags for consistency. + +I don't know what this method does! +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +No problem. Leave it behind, and list the methods you skipped when you request a +pull of your changes. Another writer will take care of it. + +You can still look at the methods' implementation in Godot's source code on +GitHub. If you have doubts, feel free to ask on the `Q&A website +`__ and `Godot Contributors Chat `_. diff --git a/community/contributing/code_style_guidelines.rst b/community/contributing/code_style_guidelines.rst index f7064b9e3..d53a8f58c 100644 --- a/community/contributing/code_style_guidelines.rst +++ b/community/contributing/code_style_guidelines.rst @@ -48,6 +48,11 @@ setup clang-format locally to check and automatically fix all your commits. ``/* clang-format off */`` and ``/* clang-format on */`` to tell clang-format to ignore a chunk of code. +.. seealso:: + + These guidelines only cover code formatting. See :ref:`doc_cpp_usage_guidelines` + for a list of language features that are permitted in pull requests. + Using clang-format locally ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -117,9 +122,13 @@ Here is a non-exhaustive list of beautifier plugins for some IDEs: - Visual Studio Code: `Clang-Format `__ - Visual Studio: `ClangFormat `__ - vim: `vim-clang-format `__ +- CLion: Starting from version ``2019.1``, no plugin is required. Instead, enable + `ClangFormat `__ (Pull requests welcome to extend this list with tested plugins.) +.. _doc_code_style_guidelines_header_includes: + Header includes ~~~~~~~~~~~~~~~ @@ -186,7 +195,7 @@ Example: #include "core/hash_map.h" #include "core/list.h" - #include "scene/gui/control.h + #include "scene/gui/control.h" #include @@ -229,7 +238,7 @@ Example: #include "my_new_file.h" #include "core/math/math_funcs.h" - #include "scene/gui/line_edit.h + #include "scene/gui/line_edit.h" #include #include @@ -254,7 +263,7 @@ Blacken your Python changes using `Black `__. Using black locally ~~~~~~~~~~~~~~~~~~~ -First of all, you will need to install black. Black requires Python 3.6.0+ +First of all, you will need to install black. Black requires Python 3.6.0+ to run. Installation diff --git a/community/contributing/content_guidelines.rst b/community/contributing/content_guidelines.rst new file mode 100644 index 000000000..2c40103f5 --- /dev/null +++ b/community/contributing/content_guidelines.rst @@ -0,0 +1,97 @@ +.. _doc_content_guidelines: + +Content guidelines +================== + +This document is here to help us assess what we should include in the official +documentation. Below, you will find a couple of principles and recommendations +to write accessible content. + +We want to achieve two goals: + +1. **Empathize with our users.** We should write in a way that makes it easy for + them to learn from the docs. +2. **Write a complete reference manual**. Our goal here is not to teach + programming foundations. Instead, we should provide a reference for how + Godot's features work. + +Guidelines and principles +------------------------- + +Below are the guidelines we should strive to follow. They are not hard rules, +though: exceptionally, a topic will require breaking one or more of these. +Still, we should strive to achieve the two goals listed above. + +Writing complete and accessible documentation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**A feature doesn't exist unless it is documented**. If a user can't find +information about a feature and how it works, it doesn't exist to them. We +should ensure that we cover everything Godot does. + +.. note:: + + When adding or updating an engine feature, the documentation team needs to + know about it. Contributors should open an issue on the `godot-docs` repository + when their work gets merged and requires documentation. + +Do your best to keep documents **under 1000 words in length**. If a page goes +past that threshold, consider splitting it into two parts if possible. Limiting +page size forces us to write concisely and to break large documents so they each +focus on a particular problem. + +Make it clear what **problem** each page or section of a page tackles and what +the user will learn from it. Users need to know if they're reading the correct +guide to solving problems they encounter. For example, instead of writing the +heading "Signals", consider writing "Reacting to changes with signals". The +second title makes it clear what the purpose of signals is. + +.. note:: + + Long section titles lead to long entries in the side menu, which can make + navigation cumbersome. Try to keep headings five words long or less. + +If the page assumes specific knowledge of other Godot features, mention it and +link it to the corresponding documentation. For instance, a page about physics +may use signals, in which case we could note that the page that introduces +signals is a pre-requisite. + +Limiting cognitive load +~~~~~~~~~~~~~~~~~~~~~~~ + +Limit the cognitive load required to read the documentation. The simpler and +more explicit language we use, the more efficient it becomes for people to +learn. You can do so by: + +1. Introducing only one new concept at a time whenever possible. +2. Using simple English, as we recommend in our writing guidelines. +3. Including one or more **concrete usage examples**. Prefer a real-world example + to abstract code like ``foobar``. + +While many people may understand more complex language and abstract examples, +you will lose others. Also, understandable writing and practical examples +benefit everyone. + +Always make an effort to **put yourself in the user's shoes**. When we +understand something thoroughly, it becomes evident to us. We may fail to think +about details relevant to a newcomer, but **good documentation meets users where +they are**. We should strive to explain each feature's capabilities or intended +uses with the most straightforward language possible. + +Try to remember what you first needed to know when learning about the feature or +concept. What new terms did you need to learn? What confused you? What was the +hardest to grasp? You will want users to review your work, and we recommend you +practice explaining the feature before writing about it. + +.. note:: + + Having programming foundations is a pre-requisite to use a complex engine + like Godot. Talking about variables, functions, or classes is acceptable. + But we should favor plain language over specific terminology like + "metaprogramming". If you need to use precise terms, be sure to define them. + +When a page assumes knowledge of another engine feature, declare it at the +beginning and link to resources that cover what users need. You may also link to +other websites for pre-requisites beyond the documentation's scope. For example, +you could link to an introduction to programming in the getting started guide, or a +website that teaches math theory in the math section. diff --git a/community/contributing/contributing_to_the_documentation.rst b/community/contributing/contributing_to_the_documentation.rst new file mode 100644 index 000000000..9158d698e --- /dev/null +++ b/community/contributing/contributing_to_the_documentation.rst @@ -0,0 +1,188 @@ +.. _doc_contributing_to_the_documentation: + +Contributing to the documentation +================================= + +This guide explains how to contribute to Godot's documentation, be it by +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`. + +Getting started +--------------- + +To modify or create pages in the reference manual, you need to edit ``.rst`` +files in the `godot-docs GitHub repository +`_. Modifying those pages in a pull +request triggers a rebuild of the online documentation upon merging. + +.. 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 + 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 + from them. If you want to update the description of a class, its + methods, or properties, read + :ref:`doc_updating_the_class_reference`. + +What is the Godot documentation +------------------------------- + +The Godot documentation is intended as a comprehensive reference manual for the +Godot game engine. It is not meant to contain step-by-step tutorials, except for +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 + 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. + +Contributing changes +-------------------- + +**Pull Requests should use the** ``master`` **branch by default.** Only make Pull +Requests against other branches (e.g. ``2.1`` or ``3.0``) if your changes only +apply to that specific version of Godot. + +Though less convenient to edit than a wiki, this Git repository is where we +write the documentation. Having direct access to the source files in a revision +control system is a plus to ensure our documentation quality. + +Editing existing pages +~~~~~~~~~~~~~~~~~~~~~~ + +To edit an existing page, locate its ``.rst`` source file and open it in your +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. + +.. seealso:: To build the manual and test changes on your computer, see + :ref:`doc_building_the_manual`. + +Editing pages online +-------------------- + +You can edit the documentation online by clicking the **Edit on GitHub** link in +the top-right of every page. + +Doing so takes you to the GitHub text editor. You need to have a GitHub account +and to log in to use it. Once logged in, you can propose change like so: + +1. Click the **Edit on GitHub** button. + +2. On the GitHub page you're taken to, click the pencil icon in the top-right + corner near the **Raw**, **Blame**, and **Delete** buttons. It has the + tooltip "Fork this project and edit the file". + +3. Edit the text in the text editor. + +4. At the bottom of the web page, summarize the changes you made and click the + button **Propose file change**. Make sure to replace the placeholder "Update file.rst" + by a short but clear one-line description, as this is the commit title. + +5. On the following screens, click the **Create pull request** button until you + see a message like *Username wants to merge 1 commit into godotengine:master + from Username:patch-1*. + +Another contributor will review your changes and merge them into the docs if +they're good. They may also make changes or ask you to do so before merging. + +Adding new pages +---------------- + +Before adding a new page, please ensure that it fits in the documentation: + +1. Look for `existing issues + `_ 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`. + +To add a new page, create a ``.rst`` file with a meaningful name in the section you +want to add a file to, e.g. ``tutorials/3d/light_baking.rst``. + +You should then add your page to the relevant "toctree" (table of contents, +e.g. ``tutorials/3d/index.rst``). Add your new filename to the list on a new +line, using a relative path and no extension, e.g. here ``light_baking``. + +Titles +~~~~~~ + +Always begin pages with their title and a Sphinx reference name: + +:: + + .. _doc_insert_your_title_here: + + Insert your title here + ====================== + +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 lack of leading underscore in the reference). + +Write your titles like plain sentences, without capitalizing each word: + +- **Good:** Understanding signals in Godot +- **Bad:** Understanding Signals In Godot + +Only propers nouns, projects, people, and node class names should have their +first letter capitalized. + +Sphinx and reStructuredText syntax +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Check Sphinx’s `reST Primer `__ +and the `official reference `__ for +details on the syntax. + +Sphinx uses specific reST comments to do specific operations, like defining the +table of contents (``.. toctree::``) or cross-referencing pages. Check the +`official Sphinx documentation +`__ for more details. To learn +how to use Sphinx directives like ``.. note::`` or ``.. seealso::``, check out +the `Sphinx directives documentation +`__. + +Adding images and attachments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To add images, please put them in an ``img/`` folder next to the ``.rst`` file with +a meaningful name and include them in your page with: + +.. code:: rst + + .. image:: img/image_name.png + +Similarly, you can include attachments, like assets as support material for a +tutorial, by placing them into a ``files/`` folder next to the ``.rst`` file, and +using this inline markup: + +.. code:: rst + + :download:`myfilename.zip ` + + +License +------- + +This documentation and every page it contains is published under the terms of +the `Creative Commons Attribution 3.0 license (CC-BY-3.0) +`_, with +attribution to "Juan Linietsky, Ariel Manzur and the Godot community". + +By contributing to the documentation on the GitHub repository, you agree that +your changes are distributed under this license. diff --git a/community/contributing/cpp_usage_guidelines.rst b/community/contributing/cpp_usage_guidelines.rst new file mode 100644 index 000000000..f8a404e3d --- /dev/null +++ b/community/contributing/cpp_usage_guidelines.rst @@ -0,0 +1,100 @@ +.. _doc_cpp_usage_guidelines: + +C++ usage guidelines +==================== + +Rationale +--------- + +Since Godot 4.0, the C++ standard used throughout the codebase is a subset of +**C++17**. While modern C++ brings a lot of opportunities to write faster, more +readable code, we chose to restrict our usage of C++ to a subset for a few +reasons: + +- It makes it easier to review code in online editors. This is because engine + contributors don't always have access to a full-featured IDE while reviewing + code. +- It makes the code easier to grasp for beginner contributors (who may not be + professional C++ programmers). Godot's codebase is known to be easy to learn + from, and we'd like to keep it that way. + +To get your pull request merged, it needs to follow the C++ usage guidelines +outlined here. Of course, you can use features not allowed here in your own C++ +modules or GDNative scripts. + +.. note:: + + Prior to Godot 4.0, the C++ standard used throughout the codebase was C++03, + with a handful of C++14 extensions. If you are contributing a pull request + to the `3.x` branch rather than `master`, your code can't use C++17 features. + Instead, your code must be able to be built with a C++14 compiler. + + 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`. + +.. seealso:: + + See :ref:`doc_code_style_guidelines` for formatting guidelines. + +Disallowed features +------------------- + +**Any feature not listed below is allowed.** Using features like ``constexpr`` +variables and ``nullptr`` is encouraged when possible. Still, try to keep your +use of modern C++ features conservative. Their use needs to serve a real +purpose, such as improving code readability or performance. + +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. + +This means that pull requests should **not** use ``std::string``, +``std::vector`` and the like. Instead, use Godot's datatypes as described below: + +- Use ``String`` instead of ``std::string``. +- Use ``Vector`` instead of ``std::vector``. In some cases, ``List`` or + ``LocalVector`` can be used as an alternative (ask core developers first). +- Use ``Array`` instead of ``std::array``. + +``auto`` keyword +^^^^^^^^^^^^^^^^ + +Please don't use the ``auto`` keyword for type inference. While it can avoid +repetition, it can also lead to confusing code: + +.. code-block:: cpp + + // Not so confusing... + auto button = memnew(Button); + + // ...but what about this? + auto result = EditorNode::get_singleton()->get_complex_result(); + +Keep in mind hover documentation often isn't readily available for pull request +reviewers. Most of the time, reviewers will use GitHub's online viewer to review +pull requests. + +We chose to forbid ``auto`` instead of allowing it on a case-by-case basis to +avoid having to decide on difficult edge cases. Thank you for your understanding. + +Lambdas +^^^^^^^ + +Lambdas should be used conservatively when they make code effectively faster or +simpler, and do not impede readability. Please ask before using lambdas in a +pull request. + +``#pragma once`` directive +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To follow the existing style, please use standard ``#ifdef``-based include +guards instead of ``#pragma once`` in new files. + +.. seealso:: + + See :ref:`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 4d0ea2e07..2618aa5b0 100644 --- a/community/contributing/docs_writing_guidelines.rst +++ b/community/contributing/docs_writing_guidelines.rst @@ -32,6 +32,11 @@ There are 3 rules to describe classes: the smallest and clearest sentences possible. These guidelines will help you work towards that goal. +.. seealso:: + + See the :ref:`content guidelines ` for information + on the types of documentation you can write in the official documentation. + 7 rules for clear English ------------------------- @@ -105,7 +110,7 @@ The progressive forms describe continuous actions. E.g. "is calling", Vector2 move ( Vector2 rel_vec ) Move the body in the given direction, **stopping** if there is an obstacle. [...] -**Do** use simple present, preterit or future. +**Do** use simple present, past, or future. :: @@ -295,7 +300,7 @@ The exception is topics that explain static typing concepts to users. const MainAttack := preload("res://fire_attack.gd") var hit_points := 5 var name: String = "Bob" - var body_sprite := $Sprite as Sprite + var body_sprite := $Sprite2D as Sprite2D **Do** write constants and variables with dynamic typing: @@ -305,14 +310,14 @@ The exception is topics that explain static typing concepts to users. const MainAttack = preload("res://fire_attack.gd") var hit_points = 5 var name = "Bob" - var body_sprite = $Sprite + var body_sprite = $Sprite2D **Don't** write functions with inferred arguments or return types: :: - func choose(arguments: PoolStringArray) -> String: + func choose(arguments: PackedStringArray) -> String: # Chooses one of the arguments from array with equal chances randomize() var size := arguments.size() diff --git a/community/contributing/documentation_guidelines.rst b/community/contributing/documentation_guidelines.rst index faaafe42d..9320710e3 100644 --- a/community/contributing/documentation_guidelines.rst +++ b/community/contributing/documentation_guidelines.rst @@ -25,9 +25,11 @@ documentation. describes regarding the main godotengine/godot repository is also valid for the docs repository. -The README.md file contains all the information you need to get you started, -please read it. In particular, it contains some tips and tricks and links to -reference documentation about the reStructuredText markup language. +.. warning:: The class reference's source files are in the `Godot engine repository + `_. We generate the :ref:`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`. .. warning:: If you want to edit the **API reference**, please note that it should *not* be done in the godot-docs repository. Instead, you diff --git a/community/contributing/editor_and_docs_localization.rst b/community/contributing/editor_and_docs_localization.rst index 844258bfd..d97c4b471 100644 --- a/community/contributing/editor_and_docs_localization.rst +++ b/community/contributing/editor_and_docs_localization.rst @@ -112,7 +112,7 @@ translation interface where all the work happens: On that page, you have: - A toolbar which lets you cycle through strings of the current list, change - to another pre-defined list or do a custom search, etc. There is also a "Zen" + to another predefined list or do a custom search, etc. There is also a "Zen" editing mode with a simplified interface. - The actual string you are working on in the "Translation" panel. By default, there should be the English source string and an edit box for your language. @@ -171,8 +171,8 @@ translating. a page that you want to translate, and then translate all the strings with the same source string location while comparing with the online version of that page in English. An example of source string location could be - ``getting_started/step_by_step/scenes_and_nodes.rst`` for the - page :ref:`doc_scenes_and_nodes`. + ``getting_started/step_by_step/nodes_and_scenes.rst`` for the + page :ref:`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 @@ -184,7 +184,7 @@ translating. A handy tool to locate specific pages/classes is to use Weblate's advanced search feature, and especially the "Location strings" query (which can also be -used with the ``location:`` token, e.g. ``location:scenes_and_nodes.rst``): +used with the ``location:`` token, e.g. ``location:nodes_and_scenes.rst``): .. image:: img/l10n_05_search_location.png @@ -194,9 +194,9 @@ used with the ``location:`` token, e.g. ``location:scenes_and_nodes.rst``): When a given source string is used in multiple source locations, they will all be concatenated into one. For example, the above - ``location:scenes_and_nodes.rst`` query would land first on the + ``location:nodes_and_scenes.rst`` query would land first on the "Introduction" source string which is used in dozens of pages, including - some that come before ``scenes_and_nodes.rst`` in the template. Clicking the + some that come before ``nodes_and_scenes.rst`` in the template. Clicking the "Next" button then brings us to the "Scene and nodes" title string displayed above. So it may happen that a given paragraph or section title is not at the @@ -243,6 +243,10 @@ The editor translations originate from C++ strings, and may use: Scene '%s' is currently being edited.↵ Changes will only take effect when reloaded. +.. note:: + Only logical order of the characters matters, in the right-to-left text, format + specifiers may be displayed as ``s%``. + Online documentation (RST) ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -324,7 +328,7 @@ breaks if they are not part of the original translation. .. seealso:: See our documentation for class reference writers for the :ref:`list of - BBCode-like tags ` which are used + BBCode-like tags ` which are used throughout the class reference. Offline translation and testing diff --git a/community/contributing/img/best_practices1.png b/community/contributing/img/best_practices1.png index 65763b509..96d3d1229 100644 Binary files a/community/contributing/img/best_practices1.png and b/community/contributing/img/best_practices1.png differ diff --git a/community/contributing/img/best_practices2.png b/community/contributing/img/best_practices2.png index d0a8b5ba1..364e86a06 100644 Binary files a/community/contributing/img/best_practices2.png and b/community/contributing/img/best_practices2.png differ diff --git a/community/contributing/img/best_practices3.png b/community/contributing/img/best_practices3.png index 2a5dd91e5..3ecd55461 100644 Binary files a/community/contributing/img/best_practices3.png and b/community/contributing/img/best_practices3.png differ diff --git a/community/contributing/img/best_practices4.png b/community/contributing/img/best_practices4.png index 811d7f9db..bcc442888 100644 Binary files a/community/contributing/img/best_practices4.png and b/community/contributing/img/best_practices4.png differ diff --git a/community/contributing/img/best_practices5.png b/community/contributing/img/best_practices5.png index 7c3a2e81f..5a50c2e21 100644 Binary files a/community/contributing/img/best_practices5.png and b/community/contributing/img/best_practices5.png differ diff --git a/community/contributing/img/best_practices6.png b/community/contributing/img/best_practices6.png index fd27c1b87..d8aa630cc 100644 Binary files a/community/contributing/img/best_practices6.png and b/community/contributing/img/best_practices6.png differ diff --git a/community/contributing/img/best_practices7.png b/community/contributing/img/best_practices7.png index f0cab3845..4bd0aa180 100644 Binary files a/community/contributing/img/best_practices7.png and b/community/contributing/img/best_practices7.png differ diff --git a/community/contributing/img/best_practices8.png b/community/contributing/img/best_practices8.png index d277ff6ad..3c3dccd95 100644 Binary files a/community/contributing/img/best_practices8.png and b/community/contributing/img/best_practices8.png differ diff --git a/community/contributing/img/editor-vocabulary-overview.png b/community/contributing/img/editor-vocabulary-overview.png index ad95aa1b1..066f2562a 100644 Binary files a/community/contributing/img/editor-vocabulary-overview.png and b/community/contributing/img/editor-vocabulary-overview.png differ diff --git a/community/contributing/img/github_fork_button.png b/community/contributing/img/github_fork_button.png index a80fa1b61..aa4436e3e 100644 Binary files a/community/contributing/img/github_fork_button.png and b/community/contributing/img/github_fork_button.png differ diff --git a/community/contributing/img/github_fork_make_pr.png b/community/contributing/img/github_fork_make_pr.png index a18caf725..c7a815f8b 100644 Binary files a/community/contributing/img/github_fork_make_pr.png and b/community/contributing/img/github_fork_make_pr.png differ diff --git a/community/contributing/img/github_fork_url.png b/community/contributing/img/github_fork_url.png index f3ea60fdc..eb359aea1 100644 Binary files a/community/contributing/img/github_fork_url.png and b/community/contributing/img/github_fork_url.png differ diff --git a/community/contributing/img/l10n_01_language_list.png b/community/contributing/img/l10n_01_language_list.png index 16b43c88b..8d1726f60 100644 Binary files a/community/contributing/img/l10n_01_language_list.png and b/community/contributing/img/l10n_01_language_list.png differ diff --git a/community/contributing/img/l10n_02_new_translation.png b/community/contributing/img/l10n_02_new_translation.png index 8d9213b9e..c953a3359 100644 Binary files a/community/contributing/img/l10n_02_new_translation.png and b/community/contributing/img/l10n_02_new_translation.png differ diff --git a/community/contributing/img/l10n_03_translation_overview.png b/community/contributing/img/l10n_03_translation_overview.png index 748e085d2..96642cc56 100644 Binary files a/community/contributing/img/l10n_03_translation_overview.png and b/community/contributing/img/l10n_03_translation_overview.png differ diff --git a/community/contributing/img/l10n_04_translation_interface.png b/community/contributing/img/l10n_04_translation_interface.png index f05498378..7666b03f8 100644 Binary files a/community/contributing/img/l10n_04_translation_interface.png and b/community/contributing/img/l10n_04_translation_interface.png differ diff --git a/community/contributing/img/l10n_05_search_location.png b/community/contributing/img/l10n_05_search_location.png index 7c2c2dc82..e4da602c4 100644 Binary files a/community/contributing/img/l10n_05_search_location.png and b/community/contributing/img/l10n_05_search_location.png differ diff --git a/community/contributing/img/l10n_06_browse_by_location.png b/community/contributing/img/l10n_06_browse_by_location.png index 2017900e9..ed3a392b2 100644 Binary files a/community/contributing/img/l10n_06_browse_by_location.png and b/community/contributing/img/l10n_06_browse_by_location.png differ diff --git a/community/contributing/img/l10n_07_download_po_file.png b/community/contributing/img/l10n_07_download_po_file.png index 3831dc7c1..5b71307b6 100644 Binary files a/community/contributing/img/l10n_07_download_po_file.png and b/community/contributing/img/l10n_07_download_po_file.png differ diff --git a/community/contributing/img/l10n_08_edit_on_github.png b/community/contributing/img/l10n_08_edit_on_github.png index d25f14907..7c4e7984b 100644 Binary files a/community/contributing/img/l10n_08_edit_on_github.png and b/community/contributing/img/l10n_08_edit_on_github.png differ diff --git a/community/contributing/img/l10n_09_path_to_image.png b/community/contributing/img/l10n_09_path_to_image.png index 0263ebe22..55742205c 100644 Binary files a/community/contributing/img/l10n_09_path_to_image.png and b/community/contributing/img/l10n_09_path_to_image.png differ diff --git a/community/contributing/img/testing_pull_requests_access_checks.png b/community/contributing/img/testing_pull_requests_access_checks.png index ede509c4a..1bd13ac22 100644 Binary files a/community/contributing/img/testing_pull_requests_access_checks.png and b/community/contributing/img/testing_pull_requests_access_checks.png differ diff --git a/community/contributing/img/testing_pull_requests_access_fork.png b/community/contributing/img/testing_pull_requests_access_fork.png index e6599f504..b53c8a723 100644 Binary files a/community/contributing/img/testing_pull_requests_access_fork.png and b/community/contributing/img/testing_pull_requests_access_fork.png differ diff --git a/community/contributing/img/testing_pull_requests_checks_artifacts.png b/community/contributing/img/testing_pull_requests_checks_artifacts.png index 26bde4428..25697e267 100644 Binary files a/community/contributing/img/testing_pull_requests_checks_artifacts.png and b/community/contributing/img/testing_pull_requests_checks_artifacts.png differ diff --git a/community/contributing/img/testing_pull_requests_checks_platforms.png b/community/contributing/img/testing_pull_requests_checks_platforms.png index e4e866deb..2575abc84 100644 Binary files a/community/contributing/img/testing_pull_requests_checks_platforms.png and b/community/contributing/img/testing_pull_requests_checks_platforms.png differ diff --git a/community/contributing/img/testing_pull_requests_fork_zip.png b/community/contributing/img/testing_pull_requests_fork_zip.png index 859c3cc88..07ee9f5f4 100644 Binary files a/community/contributing/img/testing_pull_requests_fork_zip.png and b/community/contributing/img/testing_pull_requests_fork_zip.png differ diff --git a/community/contributing/img/testing_pull_requests_nightly_link.png b/community/contributing/img/testing_pull_requests_nightly_link.png index 7c3d98bed..e68e5ef9c 100644 Binary files a/community/contributing/img/testing_pull_requests_nightly_link.png and b/community/contributing/img/testing_pull_requests_nightly_link.png differ diff --git a/community/contributing/index.rst b/community/contributing/index.rst index 7557cbe79..66ab5952d 100644 --- a/community/contributing/index.rst +++ b/community/contributing/index.rst @@ -1,19 +1,109 @@ Contributing ============ +Everyone is most welcome to contribute to Godot. Here are some ways in which you +can contribute to the project: + +- Improving the engine by fixing bugs, coding new features, or refining existing ones. +- Writing or proofreading documentation. You can contribute both to this + reference manual or the code reference. +- Translating the editor or documentation from English to other languages. +- Reporting issues or `writing detailed proposals + `__. + +Getting started +--------------- + +You would like to contribute but you don't know how or what to do? You can get +answers below. + .. toctree:: :maxdepth: 1 - :name: toc-community-contributing + :name: toc-community-getting-started ways_to_contribute + +.. _doc_community_contributing_to_the_engine: + +Contributing to the engine +-------------------------- + +The guides below explain how to contribute to the engine's core. You will learn +about the code style, the contribution workflow, and more. + +.. toctree:: + :maxdepth: 1 + :name: toc-community-contributing-to-the-engine + best_practices_for_engine_contributors pr_workflow testing_pull_requests bisecting_regressions - code_style_guidelines bug_triage_guidelines - building_the_manual - documentation_guidelines + code_style_guidelines + cpp_usage_guidelines + +.. _doc_community_writing_documentation: + +Writing documentation +--------------------- + +We always need help to improve the documentation, be it the class reference or +the manual. Below, you can find our content and writing guidelines and +concrete guides to make changes to the documentation. + +Guidelines +~~~~~~~~~~ + +Here are the principles and guidelines we strive to follow to write accessible +documentation. + +.. toctree:: + :maxdepth: 1 + :name: toc-community-writing-guidelines + + content_guidelines docs_writing_guidelines + documentation_guidelines + +Writing the manual +~~~~~~~~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + :name: toc-community-documentation + + contributing_to_the_documentation + building_the_manual + +Class reference guides +~~~~~~~~~~~~~~~~~~~~~~ + +The pages below focus on the class reference. + +As the reference is included in the Godot editor, its source files are part of +the `godot repository `_. We use XML files +to write it, so the process to contribute to the class reference differs from +writing the online manual. + +.. toctree:: + :maxdepth: 1 + :name: toc-community-class-reference + updating_the_class_reference + class_reference_writing_guidelines + +.. _doc_community_translating_the_documentation: + +Translating the documentation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The community is always working hard on making Godot and its documentation +available to more people. Localizing the documentation is a colossal and ongoing +effort you can be part of. + +.. toctree:: + :maxdepth: 1 + :name: toc-community-localization + editor_and_docs_localization diff --git a/community/contributing/pr_workflow.rst b/community/contributing/pr_workflow.rst index 4f6ed7b8a..5562239c4 100644 --- a/community/contributing/pr_workflow.rst +++ b/community/contributing/pr_workflow.rst @@ -47,6 +47,7 @@ which quickly leads to PRs with an unreadable Git history (especially after peer the tool's philosophy and the various commands you need to master in your daily workflow. You can read them online on the `Git SCM `_ website. + You can also try out `GitHub's interactive guide `__. The branches on the Git repository are organized as follows: @@ -364,7 +365,8 @@ On that line, there is a "Pull request" link. Clicking it will open a form that will let you issue a pull request on the ``godotengine/godot`` upstream repository. It should show you your two commits, and state "Able to merge". If not (e.g. it has way more commits, or says there are merge conflicts), -don't create the PR, something went wrong. Go to IRC and ask for support :) +don't create the PR yet, something went wrong. Go to our `Contributors Chat +`_ and ask for support :) Use an explicit title for the PR and put the necessary details in the comment area. You can drag and drop screenshots, GIFs or zipped projects if relevant, @@ -469,7 +471,7 @@ between, the most common and convenient workflow involves rebasing on the with this little by little). This will open a text editor (``vi`` by default, see -`Git docs __` +`Git docs `_ to configure your favorite one) with something which may look like this: .. code-block:: text diff --git a/community/contributing/updating_the_class_reference.rst b/community/contributing/updating_the_class_reference.rst index 4575d669a..891e1633b 100644 --- a/community/contributing/updating_the_class_reference.rst +++ b/community/contributing/updating_the_class_reference.rst @@ -5,325 +5,72 @@ Contributing to the class reference .. highlight:: shell -.. note:: This guide also is available as a `video tutorial on YouTube `_. +The class reference is available online in the :ref:`classes ` +section of the documentation and in the Godot editor, from the help menu. -Godot ships with many nodes and singletons to help you develop your games. Each is a class, documented in the :ref:`class reference `. -This reference is essential for anyone learning the engine: it is available both online and in the engine. +In the class reference, some methods, variables, and signals lack descriptions. +Others changed with recent releases and need updates. The developers can't write +the entire reference on their own. Godot needs you, and all of us, to +contribute. -But it's incomplete. Some methods, variables and signals lack descriptions. Others changed with recent releases and need updates. -The developers can't write the entire reference on their own. Godot needs you, and all of us, to contribute. - -**Important:** If you are planning to make larger changes or a more substantial contribution, it is usually a good idea -to create an issue (or a comment in an existing one) to let others know so they don't start working on the same thing too. +**Important:** If you plan to make large changes, you should create an issue on +the `godot-docs repository `_ +or comment on an existing issue. Doing so lets others know you're already +taking care of a given class. .. seealso:: - Not sure where to start contributing? Take a look at the current class reference - completion status `here `__. + You can find the writing guidelines for the class reference :ref:`here `. -How to contribute ------------------ + For details on Git usage and the pull request workflow, please + refer to the :ref:`doc_pr_workflow` page. -The class reference lies in the following XML files, in Godot's GitHub repository: `doc/classes/ `_. + If you want to translate the class reference from English to another + language, see :ref:`doc_editor_and_docs_localization`. -There are 5 steps to update the class reference (full guide below): + This guide is also available as a `video tutorial on YouTube + `_. -1. Fork `Godot's repository `_ -2. Clone your fork on your computer -3. Edit the class file in ``doc/classes/`` to write documentation -4. Commit your changes and push them to your fork -5. Make a pull request on the Godot repository +.. seealso:: -.. warning:: Always use these XML files to edit the API reference. Do not edit the generated .rst files :ref:`in the online documentation `, hosted in the `godot-docs `_ repository. + Not sure which class to contribute to? Take a look at the class reference's + completion status `here `_. -Get started with GitHub ------------------------ +You can find the source files for the class reference in Godot's GitHub +repository: `doc/classes/ +`_. -If you're new to Git and GitHub, this guide will help you get started. You'll learn to: +.. note:: For some modules in the engine's source code, you'll find the XML + files in the ``modules//doc_classes/`` directory instead. -- Fork and clone Godot's repository -- Keep your fork up to date with other contributors -- Create a pull request so your improvements end in the official docs +.. warning:: Always edit the API reference through these source XML files. Do + not edit the generated ``.rst`` files :ref:`in the online documentation + `, hosted in the `godot-docs + `_ repository. -.. note:: If you're new to Git, the version control system Godot uses, go through `GitHub's interactive guide `_. You'll learn some essential vocabulary and get a sense for the tool. +.. warning:: -Fork Godot -~~~~~~~~~~ + Unless you make minor changes, like fixing a typo, we do not recommend using the GitHub web editor to edit the class reference's XML. -Fork the Godot Engine into a GitHub repository of your own. + It lacks features to edit XML well, like keeping indentations consistent, and it does not allow amending commits based on reviews. -Clone the repository on your computer: - -:: - - git clone https://github.com/your_name/godot.git - -Create a new branch to make your changes. It makes it a lot easier to sync your improvements with other docs writers. It's also easier to clean up your repository if you run into any issues with Git. - -:: - - git checkout -b your-new-branch-name - -The new branch is the same as your master branch, until you start to write API docs. In the ``doc/`` folder, you'll find the class reference. - -How to keep your local clone up-to-date -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Other writers contribute to Godot's documentation. Your local repository will fall behind it, and you'll have to synchronize it. Especially if other contributors update the class reference while you work on it. - -First add an ``upstream`` git *remote* to work with. Remotes are links to online repositories you can download new files from. - -:: - - git remote add upstream https://github.com/godotengine/godot - -You can check the list of all remote servers with: - -:: - - git remote -v - -You should have two: ``origin``, your fork on GitHub that Git adds by default, and ``upstream``, that you just added: - - -:: - - origin https://github.com/your_name/godot.git (fetch) - origin https://github.com/your_name/godot.git (push) - upstream https://github.com/godotengine/godot.git (fetch) - upstream https://github.com/godotengine/godot.git (push) - -Each time you want to sync your branch to the state of the upstream repository, enter: - -:: - - git pull --rebase upstream master - -This command will first ``fetch``, or download the latest version of the Godot repository. Then, it will reapply your local changes on top. - -If you made changes you don't want to keep in your local branch, use the following commands instead: - -:: - - git fetch upstream - git reset --hard upstream master - -**Warning:** The above command will reset your branch to the state of the ``upstream master`` branch. It will discard all local changes. Make sure to only run this *before* you make important changes. - -Another option is to delete the branch you're working on, synchronize the master branch with the Godot repository, and create a new branch: - -:: - - git checkout master - git branch -d your-new-branch-name - git pull --rebase upstream master - git checkout -b your-new-branch-name - -If you're feeling lost by now, come to our `IRC channels `_ and ask for help. Experienced Git users will give you a hand. + 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`. Updating the documentation template ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When classes are modified in the source code, the documentation template might become outdated. To make sure that you are editing an up-to-date version, you first need to compile Godot (you can follow the :ref:`doc_introduction_to_the_buildsystem` page), and then run the following command (assuming 64-bit Linux): +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 +compiled Godot binary from the Godot root directory with the ``--doctool`` option. +For example, if you're on 64-bit Linux, the command is:: - ./bin/godot.x11.tools.64 --doctool . + ./bin/godot.linuxbsd.tools.64 --doctool -The XML files in doc/classes should then be up-to-date with current Godot Engine features. You can then check what changed using the ``git diff`` command. If there are changes to other classes than the one you are planning to document, please commit those changes first before starting to edit the template: - -:: - - git add doc/classes/*.xml - git commit -m "Sync classes reference template with current code base" - -You are now ready to edit this file to add stuff. - -**Note:** If this has been done recently by another contributor, you don't forcefully need to go through these steps (unless you know that the class you plan to edit *has* been modified recently). - -Push and request a pull of your changes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Once your modifications are finished, push your changes on your GitHub -repository: - -:: - - git add doc/classes/.xml - git commit -m "Explain your modifications." - git push - -When it's done, you can ask for a Pull Request via the GitHub UI of your Godot fork. - -.. warning:: - - Although you can edit files on GitHub, it's not recommended. As hundreds of contributors work on Godot, the Git history must stay clean. Each commit should bundle all related improvements you make to the class reference, a new feature, bug fixes... When you edit from GitHub, it will create a new branch and a Pull Request every time you want to save it. If a few days pass before your changes get a review, you won't be able to update to the latest version of the repository cleanly. Also, it's harder to keep clean indents from GitHub. And they're very important in the docs. - - TL;DR: If you don't know what you're doing exactly, do not edit files from GitHub. - -How to edit class XML ---------------------- - -Edit the file for your chosen class in ``doc/classes/`` to update the class reference. The folder contains an XML file for each class. The XML lists the constants and methods you'll find in the class reference. Godot generates and updates the XML automatically. - -Edit it using your favorite text editor. If you use a code editor, make sure that it doesn't change the indent style: tabs for the XML, and 4 spaces inside BBCode-style blocks. More on that below. - -If you need to check that the modifications you've made are correct in the generated documentation, build Godot as described :ref:`here `, run the editor and open the help for the page you modified. - -How to write the class reference -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Each class has a brief and a long description. The brief description is always at the top of the page, while the full description lies below the list of methods, variables and constants. Methods, member variables, constants and signals are in separate categories or XML nodes. For each, learn how they work in Godot's source code, and fill their . - -Our job is to add the missing text between these marks: - -- -- -- -- -- -- - -Write in a clear and simple language. Always follow the :ref:`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. - -Here's how a class looks like in XML: - -.. code-block:: xml - - - - Base node for 2D system. - - - Base node for 2D system. Node2D contains a position, rotation and scale, which is used to position and animate. It can alternatively be used with a custom 2D transform ([Matrix32]). A tree of Node2Ds allows complex hierarchies for animation and positioning. - - - - - - - Sets the position of the 2D node. - - - [...] - - - - - - - - - - - [...] - - - - - - - - -Use a code editor like Vim, Atom, Code, Notepad++ or anything similar to edit the file quickly. Use the search function to find classes fast. - -.. _doc_updating_the_class_reference_bbcode: - -Improve formatting with BBCode style tags -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Godot's class reference supports BBCode-like tags. They add nice formatting to 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`. | -+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ -| [method methodname] | Link to a method in this class | Call [method hide]. | See :ref:`hide `. | -+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ -| [method Class.methodname] | Link to another class's method | Call [method Spatial.hide]. | See :ref:`hide `. | -+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ -| [member membername] | Link to a member in this class | Get [member scale]. | Get :ref:`scale `. | -+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ -| [member Class.membername] | Link to another class's member | Get [member Node2D.scale]. | Get :ref:`scale `. | -+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ -| [signal signalname] | Link to a signal in this class | Emit [signal renamed]. | Emit :ref:`renamed `. | -+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ -| [signal Class.signalname] | Link to another class's signal | Emit [signal Node.renamed]. | Emit :ref:`renamed `. | -+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ -| [b] [/b] | Bold | Some [b]bold[/b] text. | Some **bold** text. | -+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ -| [i] [/i] | Italic | Some [i]italic[/i] text. | Some *italic* text. | -+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ -| [code] [/code] | Monospace | Some [code]monospace[/code] text. | Some ``monospace`` text. | -+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ -| [kbd] [/kbd] | Keyboard/mouse shortcut | Some [kbd]Ctrl + C[/kbd] key. | Some :kbd:`Ctrl + C` key. | -+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ -| [codeblock] [/codeblock] | Multiline preformatted block | *See below.* | *See below.* | -+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ - -Use ``[codeblock]`` for pre-formatted code blocks. Inside ``[codeblock]``, always use **four spaces** for indentation (the parser will delete tabs). Example: - -.. code-block:: none - - [codeblock] - func _ready(): - var sprite = get_node("Sprite") - print(sprite.get_pos()) - [/codeblock] - -Will display as: - -.. code-block:: gdscript - - func _ready(): - var sprite = get_node("Sprite") - print(sprite.get_pos()) - -To denote important information, add a paragraph starting with "[b]Note:[/b]" at -the end of the description: - -.. code-block:: none - - [b]Note:[/b] Only available when using the GLES2 renderer. - -To denote crucial information that could cause security issues or loss of data -if not followed carefully, add a paragraph starting with "[b]Warning:[/b]" at the -end of the description: - -.. code-block:: none - - [b]Warning:[/b] If this property is set to [code]true[/code], it allows clients to execute arbitrary code on the server. - -For deprecated properties, add a paragraph starting with "[i]Deprecated.[/i]". -Notice the use of italics instead of bold: - -.. code-block:: none - - [i]Deprecated.[/i] This property has been replaced by [member other_property]. - -In all the paragraphs described above, make sure the punctuation is part of the -BBCode tags for consistency. - -I don't know what this method does! -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -No problem. Leave it behind, and list the methods you skipped when you request a pull of your changes. Another writer will take care of it. - -You can still have a look at the methods' implementation in Godot's source code on GitHub. Also, if you have doubts, feel free to ask on the `Q&A website `__ and on IRC (freenode, #godotengine). - - -Localization -~~~~~~~~~~~~ - -The documentation can be translated in any language on `Hosted Weblate -`__. - -Translated strings are synced manually by documentation maintainers in -the `godot-docs-l10n `__ -repository. - -Languages with a good level of completion have their own localized -instances of ReadTheDocs. Open an issue on the ``godot-docs-l10n`` -repository if you think that a new language is complete enough to get -its own instance. +The XML files in doc/classes should then be up-to-date with current Godot Engine +features. You can then check what changed using the ``git diff`` command. Please +only include changes that are relevant to your work on the API in your commits. +You can discard changes in other XML files using ``git checkout``. diff --git a/community/contributing/ways_to_contribute.rst b/community/contributing/ways_to_contribute.rst index b58039788..595deada6 100644 --- a/community/contributing/ways_to_contribute.rst +++ b/community/contributing/ways_to_contribute.rst @@ -16,8 +16,8 @@ positive to the engine, regardless of their skill set: - **Be part of the community.** The best way to contribute to Godot and help it become ever better is simply to use the engine and promote it by word-of-mouth, in the credits or splash screen of your games, blog posts, tutorials, - videos, demos, gamedev or free software events, support on the Q&A, IRC, - forums, Discord, etc. Participate! + videos, demos, gamedev or free software events, support on the Q&A, forums, + Contributors Chat, Discord, etc. Participate! Being a user and advocate helps spread the word about our great engine, which has no marketing budget and can therefore only rely on its community to become more mainstream. @@ -144,7 +144,7 @@ Filing an issue on GitHub Godot uses `GitHub's issue tracker `_ for bug reports and enhancement suggestions. You will need a GitHub account to -be able to open a new issue there, and click on the "New issue" button. +be able to open a new issue there, and click on the **New issue** button. When you report a bug, you should keep in mind that the process is similar to an appointment with your doctor. You noticed *symptoms* that make you think @@ -167,7 +167,7 @@ always provide: only on certain processors, graphic cards, etc. If you are able to, it can be helpful to include information on your hardware. -- **Godot version.** This is a must have. Some issues might be relevant in the +- **Godot version.** This is a must-have. Some issues might be relevant in the current stable release, but fixed in the development branch, or the other way around. You might also be using an obsolete version of Godot and experiencing a known issue fixed in a later version, so knowing this from @@ -184,7 +184,7 @@ always provide: mind that there are thousands of issues in the tracker, and developers can only dedicate little time to each issue. -When you click the "New issue" button, you should be presented with a text area +When you click the **New issue** button, you should be presented with a text area prefilled with our issue template. Please try to follow it so that all issues are consistent and provide the required information. @@ -193,20 +193,20 @@ Contributing to the documentation 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 `. - To contribute to the class reference, you have to edit the - `doc/base/classes.xml` in Godot's Git repository, and make a pull request. - See :ref:`doc_updating_the_class_reference` for more details. +- **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 + `. 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. -- **The tutorials and engine documentation and its translations.** This is the part you are reading - now, which is distributed in the HTML, PDF and EPUB formats. 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_documentation_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. Contributing translations ------------------------- diff --git a/community/tutorials.rst b/community/tutorials.rst index d61e6b8f9..637c0d37d 100644 --- a/community/tutorials.rst +++ b/community/tutorials.rst @@ -23,6 +23,7 @@ Video tutorials - `Godot Tutorials `_ (2D, GDScript, Programming Basics). - `Emilio `_ (2D, GDScript and VisualScript). +- `FinePointCGI `_ (2D, 3D, GDScript and C#). - `GDQuest `_ (2D and 3D, GDScript, VisualScript and C#). - `Game Development Center `_ (2D, networked multiplayer, GDScript). - `Game Endeavor `_ (2D, GDScript). @@ -41,10 +42,12 @@ Video tutorials - `TheGuideKnight `_ (2D, GDScript). - `GDScript Dude `_ (GDScript). - `Garbaj `_ (3D, GDScript). +- `Kasper Frandsen `_ (3D, Shaders). Text tutorials -------------- +- `FinepointCGI website by Mitch `__ - `GDScript website by Andrew Wilkes `__ - `Godot Recipes by KidsCanCode `__ - `Steincodes `__ diff --git a/development/editor/introduction_to_editor_development.rst b/development/editor/introduction_to_editor_development.rst index 13e848de2..ed72aabd6 100644 --- a/development/editor/introduction_to_editor_development.rst +++ b/development/editor/introduction_to_editor_development.rst @@ -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 +:ref:`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. diff --git a/getting_started/editor/img/editable-children.png b/getting_started/editor/img/editable-children.png deleted file mode 100644 index 6505ed4bc..000000000 Binary files a/getting_started/editor/img/editable-children.png and /dev/null differ diff --git a/getting_started/editor/img/godot-gui-overlay.png b/getting_started/editor/img/godot-gui-overlay.png deleted file mode 100644 index 9d98d5bb0..000000000 Binary files a/getting_started/editor/img/godot-gui-overlay.png and /dev/null differ diff --git a/getting_started/editor/img/save-branch-as-scene.png b/getting_started/editor/img/save-branch-as-scene.png deleted file mode 100644 index 6c3fdd4ee..000000000 Binary files a/getting_started/editor/img/save-branch-as-scene.png and /dev/null differ diff --git a/getting_started/editor/img/unity-gui-overlay.png b/getting_started/editor/img/unity-gui-overlay.png deleted file mode 100644 index e035448bc..000000000 Binary files a/getting_started/editor/img/unity-gui-overlay.png and /dev/null differ diff --git a/getting_started/editor/img/unity-project-organization-example.png b/getting_started/editor/img/unity-project-organization-example.png deleted file mode 100644 index cc97154d9..000000000 Binary files a/getting_started/editor/img/unity-project-organization-example.png and /dev/null differ diff --git a/getting_started/editor/index.rst b/getting_started/editor/index.rst deleted file mode 100644 index dbb101889..000000000 --- a/getting_started/editor/index.rst +++ /dev/null @@ -1,13 +0,0 @@ - -Editor manual -============= - -.. toctree:: - :maxdepth: 1 - :name: toc-learn-editor - - using_the_web_editor - command_line_tutorial - external_editor - default_key_mapping - unity_to_godot diff --git a/getting_started/editor/unity_to_godot.rst b/getting_started/editor/unity_to_godot.rst deleted file mode 100644 index f0dc90ee7..000000000 --- a/getting_started/editor/unity_to_godot.rst +++ /dev/null @@ -1,253 +0,0 @@ -.. _unity_to_godot: - -.. references : -.. https://wiki.unrealengine.com/Unity3D_Developer's_Guide_to_Unreal_Engine_4 -.. https://docs.unrealengine.com/latest/INT/GettingStarted/FromUnity/ - -From Unity to Godot Engine -========================== - -This guide provides an overview of Godot Engine from the viewpoint of a Unity user, -and aims to help you migrate your existing Unity experience into the world of Godot. - -.. note:: - - This article talks about older versions of Unity. Nestable prefabs ('Nested prefabs') were added to Unity 2018.3. Nestable prefabs are analogous to Godot's scenes, and allow a more Godot-like approach to scene organization. - -Differences ------------ - -+-------------------+------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------+ -| | Unity | Godot | -+===================+====================================================================================+================================================================================================================+ -| License | Proprietary, closed, free license with revenue caps and usage restrictions | MIT license, free and fully open source without any restriction | -+-------------------+------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------+ -| OS (editor) | Windows, macOS, Linux | Windows, macOS, X11 (Linux, \*BSD) | -+-------------------+------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------+ -| OS (export) | * **Desktop:** Windows, macOS, Linux | * **Desktop:** Windows, macOS, X11 | -| | * **Mobile:** Android, iOS, Windows Phone, Tizen | * **Mobile:** Android, iOS | -| | * **Web:** WebAssembly or asm.js | * **Web:** WebAssembly | -| | * **Consoles:** PS4, PS Vita, Xbox One, Xbox 360, Wii U, Nintendo 3DS | * **Console:** See :ref:`doc_consoles` | -| | * **VR:** Oculus Rift, SteamVR, Google Cardboard, PlayStation VR, Gear VR, HoloLens| * **VR:** Oculus Rift, SteamVR | -| | * **TV:** Android TV, Samsung SMART TV, tvOS | | -+-------------------+------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------+ -| Scene system | * Component/Scene (GameObject > Component) | :ref:`Scene tree and nodes `, allowing scenes to be nested and/or inherit other scenes | -| | * Prefabs | | -+-------------------+------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------+ -| Third-party tools | Visual Studio or VS Code | * :ref:`External editors are possible ` | -| | | * :ref:`Android SDK for Android export ` | -+-------------------+------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------+ -| Notable advantages| * Huge community | * Scene System | -| | * Large assets store | * :ref:`Animation Pipeline ` | -| | | * :ref:`Easy to write Shaders ` | -| | | * Debug on Device | -| | | | -| | | | -+-------------------+------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------+ - - -The editor ----------- - -Godot Engine provides a rich-featured editor that allows you to build your games. -The pictures below display the default layouts of both editors with colored blocks to indicate common functionalities. - -.. image:: img/unity-gui-overlay.png -.. image:: img/godot-gui-overlay.png - -While both editors may seem similar, there are many differences below the surface. -Both let you organize the project using the filesystem, -but Godot's approach is simpler with a single configuration file, minimalist text format, -and no metadata. This makes Godot more friendly to VCS systems, such as Git, Subversion, or Mercurial. - -Godot's Scene panel is similar to Unity's Hierarchy panel but, as each node has a specific function, -the approach used by Godot is more visually descriptive. It's easier to understand -what a scene does at a glance. - -The Inspector in Godot is more minimal, it shows only properties. -Thanks to this, objects can expose more useful parameters to the user -without having to hide functionality in language APIs. As a plus, Godot allows animating any of those properties visually. -Changing colors, textures, enumerations, or even links to resources in real-time is possible without needing to write code. - -The Toolbar at the top of the screen is similar in both editors, offering control over project playback. -Projects in Godot run in a separate window, rather than inside the editor -(but the tree and objects can still be explored in the debugger window). - -This approach has several advantages: - -- Running the project and closing it is fast (Unity has to save, run the project, close the project, and then reload the previous state). -- Live editing is a lot more useful because changes done to the editor take effect immediately in the game and are not lost (nor have to be synced) when the game is closed. This allows fantastic workflows, like creating levels while you play them. -- The editor is more stable because the game runs in a separate process. -- The running game can be explored from different angles by toggling the "Camera Override" button in the editor viewport, which will switch between using the editor view and the game camera view. - -Finally, Godot's top toolbar includes a menu for remote debugging. -These options allow deployment to a device (connected phone, tablet, or browser via HTML5), -and debugging/live editing on it after the game is exported. - -The scene system ----------------- - -This is the most important difference between Unity and Godot and the favorite feature of most Godot users. - -Working on a 'level' in Unity usually means embedding all the required assets in a scene -and linking them together with components and scripts. - -Godot's scene system is superficially similar to Unity. A 'level' consists of a collection of nodes, each with its own purpose: Sprite, Mesh, Light, etc. However, in Godot the nodes are arranged in a tree. Each node can have multiple children, which makes each a subscene of the main scene. -This means you can compose a whole scene with different scenes stored in different files. - -For example, think of a platformer level. You would compose it with multiple elements: - -- Bricks -- Coins -- The player -- The enemies - -In Unity, you would put all the GameObjects in the scene: the player, multiple instances of enemies, -bricks everywhere to form the ground of the level and then multiple instances of coins all over the level. -You would then add various components to each element to link them and add logic in the level: For example, -you'd add a BoxCollider2D to all the elements of the scene so that they can collide. This principle is different in Godot. - -In Godot, you would split your whole scene into three separate, smaller scenes, and instance them in the main scene. - -1. **A scene for the Player alone.** - -Consider the player as an element we'd like to use in different parent scenes (for instance 'level' scenes). In our case, the player element needs at least an AnimatedSprite node. This node contains the sprite textures necessary for various animations (for example, a walking animation). - -2. **A scene for the Enemy.** - -An enemy is also an element we'd like to use in several scenes. It's almost the same -as the Player node. The only differences are the script (it needs 'AI' routines to generate the enemy's behavior) -and the sprite textures used by the AnimatedSprite node. - -3. **A Level scene.** - -A Level scene is composed of Bricks (for platforms), Coins (for the player to collect) and a -number of instances of the Enemy scene. Each instance is a node in the Level scene tree. These instances are separate enemies, -which initially have shared behavior and appearance as defined in the Enemy scene. You can set different properties for each Enemy node (to change its color, for example). - -4. **A Main scene.** -The Main scene would be composed of one root node with 2 children: a Player instance node, and a Level instance node. -The root node can be anything, generally a "root" type such as "Node" which is the most global type, -or "Node2D" (root type of all 2D-related nodes), "Spatial" (root type of all 3D-related nodes) or -"Control" (root type of all GUI-related nodes). - -As you can see, every scene is organized as a tree. The same goes for nodes' properties: you don't *add* a -collision component to a node to make it collidable like Unity does. Instead, you make this node a *child* of a -new specific node that has collision properties. Godot features various collision types nodes, depending on the usage -(see the :ref:`Physics introduction `). - -- What are the advantages of this system? Wouldn't this system potentially increase the depth of the scene tree? And doesn't Unity already allow you to organize GameObjects by putting them inside empty GameObjects? - - - Godot's system is closer to the well-known object-oriented paradigm: Godot provides a number of nodes which are not clearly "Game Objects", but they provide their children with their own capabilities: this is inheritance. - - Godot allows the extraction of a subtree of a scene to make it a scene of its own. So if a scene tree gets too deep, it can be split into smaller subtrees. This is better for reusability, as you can include any subtree as a child of any node. Putting multiple GameObjects in an empty GameObject in Unity does not provide the same functionality. - -Project organization --------------------- - -.. image:: img/unity-project-organization-example.png - -There is no perfect project architecture. -Any architecture can be made to work in either Unity and Godot. - -However, a common architecture for Unity projects is to have one Assets folder in the root directory -that contains various folders, one per type of asset: Audio, Graphics, Models, Materials, Scripts, Scenes, and so on. - -Since Godot allows splitting scenes into smaller scenes, each scene and subscene existing as a file in the project, we recommend organizing your project a bit differently. -This wiki provides a page for this: :ref:`doc_project_organization`. - - -Where are my prefabs? ---------------------- - -A prefab as provided by Unity is a 'template' element of the scene. -It is reusable, and each instance of the prefab that exists in the scene has an existence of its own, -but all of them have the same properties as defined by the prefab. - -Godot does not provide prefabs as such, but the same functionality is provided by its scene system: -The scene system is organized as a tree. Godot allows you to save any subtree of a scene as a scene file. This new scene can then be instanced as many times as you want, as a child of any node. -Any change you make to this new, separate scene will be applied to its instances. -However, any change you make to the instance will not have any impact on the 'template' scene. - -.. image:: img/save-branch-as-scene.png - -To be precise, you can modify the parameters of an instance in the Inspector panel. -The nodes that compose this instance are initially locked. You can unlock them if you need to by -right-clicking the instance in the Scene tree and selecting "Editable children" in the menu. -You don't need to do this to add *new* child nodes to this node. -Remember that any new children will belong to the instance, not to the 'template' scene on disk. -If you want to add new children to every instance of your 'template' scene, then you should add them in the 'template' scene. - -.. image:: img/editable-children.png - -Glossary correspondence ------------------------ - -- GameObject -> Node -- Add a component -> Inheriting -- Prefab -> Reusable Scene file - - -Scripting: GDScript, C# and Visual Script ------------------------------------------ - -Design -^^^^^^ - -Unity supports C#. C# benefits from its integration with Visual Studio and has desirable features such as static typing. - -Godot provides its own scripting language, :ref:`GDScript ` as well as support -for :ref:`Visual Script ` and :ref:`C# `. -GDScript borrows its syntax from Python, but is not related to it. If you wonder about the reasoning for a custom scripting language, -please read the :ref:`doc_gdscript` and :ref:`doc_faq` pages. GDScript is strongly attached to the Godot API -and doesn't take long to learn: Between one evening for an experienced programmer and a week for a complete beginner. - -Unity allows you to attach as many scripts as you want to a GameObject. -Each script adds a behavior to the GameObject: For example, you can attach a script so that it reacts to the player's controls, -and another that controls its specific game logic. - -In Godot, you can only attach one script per node. You can use either an external GDScript file -or include the script directly in the node. If you need to attach more scripts to one node, then you may consider two solutions, -depending on your scene and on what you want to achieve: - -- either add a new node between your target node and its current parent, then add a script to this new node. -- or, you can split your target node into multiple children and attach one script to each of them. - -As you can see, it can be easy to turn a scene tree to a mess. Consider splitting any complicated scene into multiple, smaller branches. - -Connections: groups and signals -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -You can control nodes by accessing them via script and calling built-in -or user-defined functions on them. You can also place nodes in a group -and call functions on all nodes in this group. See more in the -:ref:`scripting documentation `. - -Nodes can send a signal when a specified action occurs. A signal can -be set to call any function. You can define custom signals and specify -when they are triggered. See more in the :ref:`signals documentation `. - -Script serialization -^^^^^^^^^^^^^^^^^^^^ - -Unity can handle script serialization in two ways: - -- Implicit: All public fields in a class are automatically serialized if the type is a serializable type (``Dictionary`` is not serializable). -- Explicit: Non-public fields can be serialized using the ``[SerializeField]`` attribute. - -Godot also has a built-in script serialization system, but it works only explicitly. -You can serialize any serializable type (:ref:`built-in and various engine types `, -including :ref:`class_Array` and :ref:`class_Dictionary`) using the ``export`` keyword. -See the :ref:`exports documentation ` for details. - -Unity also has a data type called ``ScriptableObject`` used to serialize custom asset objects. -Its equivalent in Godot is the base class for all resources: :ref:`class_Resource`. -Creating a script that inherits :ref:`class_Resource` will allow you to create custom serializable objects. More information about resources can be found :ref:`here `. - -Using Godot in C++ ------------------- - -Godot allows you to develop your project directly in C++ by using its API, which is not possible with Unity at the moment. -As an example, you can consider Godot Engine's editor as a "game" written in C++ using the Godot API. - -If you are interested in using Godot in C++, you may want to start reading the :ref:`Developing in -C++ ` page. diff --git a/getting_started/first_2d_game/01.project_setup.rst b/getting_started/first_2d_game/01.project_setup.rst new file mode 100644 index 000000000..84a88bf6c --- /dev/null +++ b/getting_started/first_2d_game/01.project_setup.rst @@ -0,0 +1,77 @@ +.. _doc_your_first_2d_game_project_setup: + +Setting up the project +====================== + +In this short first part, we'll set up and organize the project. + +Launch Godot and create a new project. + +.. image:: img/new-project-button.png + +.. tabs:: + .. tab:: GDScript + + Download :download:`dodge_assets.zip `. + The archive contains the images and sounds you'll be using + to make the game. Extract the archive and move the ``art/`` + and ``fonts/`` directories to your project's directory. + + .. tab:: C# + + Download :download:`dodge_assets.zip `. + The archive contains the images and sounds you'll be using + to make the game. Extract the archive and move the ``art/`` + and ``fonts/`` directories to your project's directory. + + Ensure that you have the required dependencies to use C# in Godot. + You need the .NET Core 3.1 SDK, and an editor such as VS Code. + See :ref:`doc_c_sharp_setup`. + + .. tab:: GDNative C++ + + Download :download:`dodge_assets_with_gdnative.zip + `. + The archive contains the images and sounds you'll be using + to make the game. It also contains a starter GDNative project + including a ``SConstruct`` file, a ``dodge_the_creeps.gdnlib`` + file, a ``player.gdns`` file, and an ``entry.cpp`` file. + + Ensure that you have the required dependencies to use GDNative C++. + You need a C++ compiler such as GCC or Clang or MSVC that supports C++14. + On Windows you can download Visual Studio 2019 and select the C++ workload. + You also need SCons to use the build system (the SConstruct file). + Then you need to `download the Godot C++ bindings `_ + and place them in your project. + +Your project folder should look like this. + +.. image:: img/folder-content.png + +This game is designed for portrait mode, so we need to adjust the size of the +game window. Click on *Project -> Project Settings* to open the project settings +window and in the left column, open the *Display -> Window* tab. There, set +"Width" to ``480`` and "Height" to ``720``. + +.. image:: img/setting-project-width-and-height.png + +Also, scroll down to the bottom of the section and, under the "Stretch" options, +set ``Mode`` to "2d" and ``Aspect`` to "keep". This ensures that the game scales +consistently on different sized screens. + +.. image:: img/setting-stretch-mode.png + +Organizing the project +~~~~~~~~~~~~~~~~~~~~~~ + +In this project, we will make 3 independent scenes: ``Player``, ``Mob``, and +``HUD``, which we will combine into the game's ``Main`` scene. + +In a larger project, it might be useful to create folders to hold the various +scenes and their scripts, but for this relatively small game, you can save your +scenes and scripts in the project's root folder, identified by ``res://``. You +can see your project folders in the FileSystem dock in the lower left corner: + +.. image:: img/filesystem_dock.png + +With the project in place, we're ready to design the player scene in the next lesson. diff --git a/getting_started/first_2d_game/02.player_scene.rst b/getting_started/first_2d_game/02.player_scene.rst new file mode 100644 index 000000000..ffec72c02 --- /dev/null +++ b/getting_started/first_2d_game/02.player_scene.rst @@ -0,0 +1,100 @@ +.. _doc_your_first_2d_game_player_scene: + +Creating the player scene +========================= + +With the project settings in place, we can start working on the +player-controlled character. + +The first scene will define the ``Player`` object. One of the benefits of +creating a separate Player scene is that we can test it separately, even before +we've created other parts of the game. + +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 +` node to the scene. + +.. image:: img/add_node.png + +Godot will display a warning icon next to the node in the scene tree. You can +ignore it for now. We will address it later. + +With ``Area2D`` we can detect objects that overlap or run into the player. +Change the node's name to ``Player`` by double-clicking on it. Now that we've +set the scene's root node, we can add additional nodes to give it more +functionality. + +Before we add any children to the ``Player`` node, we want to make sure we don't +accidentally move or resize them by clicking on them. Select the node and click +the icon to the right of the lock; its tooltip says "Makes sure the object's +children are not selectable." + +.. image:: img/lock_children.png + +Save the scene. Click Scene -> Save, or press :kbd:`Ctrl + S` on Windows/Linux +or :kbd:`Cmd + S` on macOS. + +.. note:: For this project, we will be following the Godot naming conventions. + + - **GDScript**: Classes (nodes) use PascalCase, variables and + functions use snake_case, and constants use ALL_CAPS (See + :ref:`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 + the method names precisely when connecting signals. + + +Sprite animation +~~~~~~~~~~~~~~~~ + +Click on the ``Player`` node and add an :ref:`AnimatedSprite2D +` 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 ``AnimatedSprite2D`` requires a :ref:`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: + +.. image:: img/spriteframes_panel.png + + +On the left is a list of animations. Click the "default" one and rename it to +"walk". Then click the "New Animation" button to create a second animation named +"up". Find the player images in the "FileSystem" tab - they're in the ``art`` +folder you unzipped earlier. Drag the two images for each animation, named +``playerGrey_up[1/2]`` and ``playerGrey_walk[1/2]``, into the "Animation Frames" +side of the panel for the corresponding animation: + +.. image:: img/spriteframes_panel2.png + +The player images are a bit too large for the game window, so we need to scale +them down. Click on the ``AnimatedSprite2D`` node and set the ``Scale`` property +to ``(0.5, 0.5)``. You can find it in the Inspector under the ``Node2D`` +heading. + +.. image:: img/player_scale.png + +Finally, add a :ref:`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 +CapsuleShape2D". Using the two size handles, resize the shape to cover the +sprite: + +.. image:: img/player_coll_shape.png + +When you're finished, your ``Player`` scene should look like this: + +.. image:: img/player_scene_nodes.png + +Make sure to save the scene again after these changes. + +In the next part, we'll add a script to the player node to move and animate it. +Then, we'll set up collision detection to know when the player got hit by +something. diff --git a/getting_started/first_2d_game/03.coding_the_player.rst b/getting_started/first_2d_game/03.coding_the_player.rst new file mode 100644 index 000000000..0d97de5a1 --- /dev/null +++ b/getting_started/first_2d_game/03.coding_the_player.rst @@ -0,0 +1,515 @@ +.. _doc_your_first_2d_game_coding_the_player: + +Coding the player +================= + +In this lesson, we'll add player movement, animation, and set it up to detect +collisions. + +To do so, we need to add some functionality that we can't get from a built-in +node, so we'll add a script. Click the ``Player`` node and click the "Attach +Script" button: + +.. image:: img/add_script_button.png + +In the script settings window, you can leave the default settings alone. Just +click "Create": + +.. note:: If you're creating a C# script or other languages, select the language + from the `language` drop down menu before hitting create. + +.. image:: img/attach_node_window.png + +.. note:: If this is your first time encountering GDScript, please read + :ref:`doc_scripting` before continuing. + +Start by declaring the member variables this object will need: + +.. tabs:: + .. code-tab:: gdscript GDScript + + extends Area2D + + export var speed = 400 # How fast the player will move (pixels/sec). + var screen_size # Size of the game window. + + .. code-tab:: csharp + + using Godot; + using System; + + public class Player : Area2D + { + [Export] + public int Speed = 400; // How fast the player will move (pixels/sec). + + public Vector2 ScreenSize; // Size of the game window. + } + + .. code-tab:: cpp + + // A `player.gdns` file has already been created for you. Attach it to the Player node. + + // Create two files `player.cpp` and `player.hpp` next to `entry.cpp` in `src`. + // This code goes in `player.hpp`. We also define the methods we'll be using here. + #ifndef PLAYER_H + #define PLAYER_H + + #include + #include + #include + #include + #include + + class Player : public godot::Area2D { + GODOT_CLASS(Player, godot::Area2D) + + godot::AnimatedSprite2D *_animated_sprite; + godot::CollisionShape2D *_collision_shape; + godot::Input *_input; + godot::Vector2 _screen_size; // Size of the game window. + + public: + real_t speed = 400; // How fast the player will move (pixels/sec). + + void _init() {} + void _ready(); + void _process(const double p_delta); + void start(const godot::Vector2 p_position); + void _on_Player_body_entered(godot::Node2D *_body); + + static void _register_methods(); + }; + + #endif // PLAYER_H + +Using the ``export`` keyword on the first variable ``speed`` allows us to set +its value in the Inspector. This can be handy for values that you want to be +able to adjust just like a node's built-in properties. Click on the ``Player`` +node and you'll see the property now appears in the "Script Variables" section +of the Inspector. Remember, if you change the value here, it will override the +value written in the script. + +.. warning:: If you're using C#, you need to (re)build the project assemblies + whenever you want to see new export variables or signals. This + build can be manually triggered by clicking the word "Mono" at the + bottom of the editor window to reveal the Mono Panel, then clicking + the "Build Project" button. + +.. image:: img/export_variable.png + +The ``_ready()`` function is called when a node enters the scene tree, which is +a good time to find the size of the game window: + +.. tabs:: + .. code-tab:: gdscript GDScript + + func _ready(): + screen_size = get_viewport_rect().size + + .. code-tab:: csharp + + public override void _Ready() + { + ScreenSize = GetViewportRect().Size; + } + + .. code-tab:: cpp + + // This code goes in `player.cpp`. + #include "player.hpp" + + void Player::_ready() { + _animated_sprite = get_node("AnimatedSprite2D"); + _collision_shape = get_node("CollisionShape2D"); + _input = godot::Input::get_singleton(); + _screen_size = get_viewport_rect().size; + } + +Now we can use the ``_process()`` function to define what the player will do. +``_process()`` is called every frame, so we'll use it to update elements of our +game, which we expect will change often. For the player, we need to do the +following: + +- Check for input. +- Move in the given direction. +- Play the appropriate animation. + +First, we need to check for input - is the player pressing a key? For this game, +we have 4 direction inputs to check. Input actions are defined in the Project +Settings under "Input Map". Here, you can define custom events and assign +different keys, mouse events, or other inputs to them. For this game, we will +just use the default events called "ui_right" etc that are assigned to the arrow +keys on the keyboard. + +You can detect whether a key is pressed using ``Input.is_action_pressed()``, +which returns ``true`` if it's pressed or ``false`` if it isn't. + +.. tabs:: + .. code-tab:: gdscript GDScript + + func _process(delta): + var velocity = Vector2.ZERO # The player's movement vector. + if Input.is_action_pressed("ui_right"): + velocity.x += 1 + if Input.is_action_pressed("ui_left"): + velocity.x -= 1 + if Input.is_action_pressed("ui_down"): + velocity.y += 1 + if Input.is_action_pressed("ui_up"): + velocity.y -= 1 + + if velocity.length() > 0: + velocity = velocity.normalized() * speed + $AnimatedSprite2D.play() + else: + $AnimatedSprite2D.stop() + + .. code-tab:: csharp + + public override void _Process(float delta) + { + var velocity = Vector2.Zero; // The player's movement vector. + + if (Input.IsActionPressed("ui_right")) + { + velocity.x += 1; + } + + if (Input.IsActionPressed("ui_left")) + { + velocity.x -= 1; + } + + if (Input.IsActionPressed("ui_down")) + { + velocity.y += 1; + } + + if (Input.IsActionPressed("ui_up")) + { + velocity.y -= 1; + } + + var animatedSprite = GetNode("AnimatedSprite2D"); + + if (velocity.Length() > 0) + { + velocity = velocity.Normalized() * Speed; + animatedSprite.Play(); + } + else + { + animatedSprite.Stop(); + } + } + + .. code-tab:: cpp + + // This code goes in `player.cpp`. + void Player::_process(const double p_delta) { + godot::Vector2 velocity(0, 0); + + velocity.x = _input->get_action_strength("move_right") - _input->get_action_strength("move_left"); + velocity.y = _input->get_action_strength("move_down") - _input->get_action_strength("move_up"); + + if (velocity.length() > 0) { + velocity = velocity.normalized() * speed; + _animated_sprite->play(); + } else { + _animated_sprite->stop(); + } + } + +We start by setting the ``velocity`` to ``(0, 0)`` - by default, the player +should not be moving. Then we check each input and add/subtract from the +``velocity`` to obtain a total direction. For example, if you hold ``right`` and +``down`` at the same time, the resulting ``velocity`` vector will be ``(1, 1)``. +In this case, since we're adding a horizontal and a vertical movement, the +player would move *faster* diagonally than if it just moved horizontally. + +We can prevent that if we *normalize* the velocity, which means we set its +*length* to ``1``, then multiply by the desired speed. This means no more fast +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`. + It's good to know but won't be necessary for the rest of this tutorial. + +We also check whether the player is moving so we can call ``play()`` or +``stop()`` on the AnimatedSprite2D. + + ``$`` is shorthand for ``get_node()``. So in the code above, + ``$AnimatedSprite2D.play()`` is the same as + ``get_node("AnimatedSprite2D").play()``. + +.. tip:: In GDScript, ``$`` returns the node at the relative path from the + current node, or returns ``null`` if the node is not found. Since + AnimatedSprite2D is a child of the current node, we can use + ``$AnimatedSprite2D``. + +Now that we have a movement direction, we can update the player's position. We +can also use ``clamp()`` to prevent it from leaving the screen. *Clamping* a +value means restricting it to a given range. Add the following to the bottom of +the ``_process`` function (make sure it's not indented under the `else`): + +.. tabs:: + .. code-tab:: gdscript GDScript + + position += velocity * delta + position.x = clamp(position.x, 0, screen_size.x) + position.y = clamp(position.y, 0, screen_size.y) + + .. code-tab:: csharp + + Position += velocity * delta; + Position = new Vector2( + x: Mathf.Clamp(Position.x, 0, ScreenSize.x), + y: Mathf.Clamp(Position.y, 0, ScreenSize.y) + ); + + .. code-tab:: cpp + + godot::Vector2 position = get_position(); + position += velocity * (real_t)p_delta; + position.x = godot::Math::clamp(position.x, (real_t)0.0, _screen_size.x); + position.y = godot::Math::clamp(position.y, (real_t)0.0, _screen_size.y); + set_position(position); + +.. tip:: The `delta` parameter in the `_process()` function refers to the *frame + length* - the amount of time that the previous frame took to complete. + Using this value ensures that your movement will remain consistent even + if the frame rate changes. + +Click "Play Scene" (:kbd:`F6`, :kbd:`Cmd + R` on macOS) and confirm you can move +the player around the screen in all directions. + +.. warning:: If you get an error in the "Debugger" panel that says + + ``Attempt to call function 'play' in base 'null instance' on a null + instance`` + + this likely means you spelled the name of the AnimatedSprite2D node + wrong. Node names are case-sensitive and ``$NodeName`` must match + the name you see in the scene tree. + +Choosing animations +~~~~~~~~~~~~~~~~~~~ + +Now that the player can move, we need to change which animation the +AnimatedSprite2D is playing based on its direction. We have the "walk" animation, +which shows the player walking to the right. This animation should be flipped +horizontally using the ``flip_h`` property for left movement. We also have the +"up" animation, which should be flipped vertically with ``flip_v`` for downward +movement. Let's place this code at the end of the ``_process()`` function: + +.. tabs:: + .. code-tab:: gdscript GDScript + + if velocity.x != 0: + $AnimatedSprite2D.animation = "walk" + $AnimatedSprite2D.flip_v = false + # See the note below about boolean assignment. + $AnimatedSprite2D.flip_h = velocity.x < 0 + elif velocity.y != 0: + $AnimatedSprite2D.animation = "up" + $AnimatedSprite2D.flip_v = velocity.y > 0 + + .. code-tab:: csharp + + if (velocity.x != 0) + { + animatedSprite2D.Animation = "walk"; + animatedSprite2D.FlipV = false; + // See the note below about boolean assignment. + animatedSprite2D.FlipH = velocity.x < 0; + } + else if (velocity.y != 0) + { + animatedSprite2D.Animation = "up"; + animatedSprite2D.FlipV = velocity.y > 0; + } + + .. code-tab:: cpp + + if (velocity.x != 0) { + _animated_sprite->set_animation("right"); + _animated_sprite->set_flip_v(false); + // See the note below about boolean assignment. + _animated_sprite->set_flip_h(velocity.x < 0); + } else if (velocity.y != 0) { + _animated_sprite->set_animation("up"); + _animated_sprite->set_flip_v(velocity.y > 0); + } + +.. Note:: The boolean assignments in the code above are a common shorthand for + programmers. Since we're doing a comparison test (boolean) and also + *assigning* a boolean value, we can do both at the same time. Consider + this code versus the one-line boolean assignment above: + + .. tabs:: + .. code-tab :: gdscript GDScript + + if velocity.x < 0: + $AnimatedSprite2D.flip_h = true + else: + $AnimatedSprite2D.flip_h = false + + .. code-tab:: csharp + + if (velocity.x < 0) + { + animatedSprite2D.FlipH = true; + } + else + { + animatedSprite2D.FlipH = false; + } + +Play the scene again and check that the animations are correct in each of the +directions. + +.. tip:: A common mistake here is to type the names of the animations wrong. The + animation names in the SpriteFrames panel must match what you type in + the code. If you named the animation ``"Walk"``, you must also use a + capital "W" in the code. + +When you're sure the movement is working correctly, add this line to +``_ready()``, so the player will be hidden when the game starts: + +.. tabs:: + .. code-tab:: gdscript GDScript + + hide() + + .. code-tab:: csharp + + Hide(); + + .. code-tab:: cpp + + hide(); + +Preparing for collisions +~~~~~~~~~~~~~~~~~~~~~~~~ + +We want ``Player`` to detect when it's hit by an enemy, but we haven't made any +enemies yet! That's OK, because we're going to use Godot's *signal* +functionality to make it work. + +Add the following at the top of the script, after ``extends Area2D``: + +.. tabs:: + .. code-tab:: gdscript GDScript + + signal hit + + .. code-tab:: csharp + + // Don't forget to rebuild the project so the editor knows about the new signal. + + [Signal] + public delegate void Hit(); + + .. code-tab:: cpp + + // This code goes in `player.cpp`. + // We need to register the signal here, and while we're here, we can also + // register the other methods and register the speed property. + void Player::_register_methods() { + godot::register_method("_ready", &Player::_ready); + godot::register_method("_process", &Player::_process); + godot::register_method("start", &Player::start); + godot::register_method("_on_Player_body_entered", &Player::_on_Player_body_entered); + godot::register_property("speed", &Player::speed, (real_t)400.0); + // This below line is the signal. + godot::register_signal("hit", godot::Dictionary()); + } + +This defines a custom signal called "hit" that we will have our player emit +(send out) when it collides with an enemy. We will use ``Area2D`` to detect the +collision. Select the ``Player`` node and click the "Node" tab next to the +Inspector tab to see the list of signals the player can emit: + +.. image:: img/player_signals.png + +Notice our custom "hit" signal is there as well! Since our enemies are going to +be ``RigidBody2D`` nodes, we want the ``body_entered(body: Node)`` signal. This +signal will be emitted when a body contacts the player. Click "Connect.." and +the "Connect a Signal" window appears. We don't need to change any of these +settings so click "Connect" again. Godot will automatically create a function in +your player's script. + +.. image:: img/player_signal_connection.png + +Note the green icon indicating that a signal is connected to this function. Add +this code to the function: + +.. tabs:: + .. code-tab:: gdscript GDScript + + func _on_Player_body_entered(body): + hide() # Player disappears after being hit. + emit_signal("hit") + # Must be deferred as we can't change physics properties on a physics callback. + $CollisionShape2D.set_deferred("disabled", true) + + .. code-tab:: csharp + + public void OnPlayerBodyEntered(PhysicsBody2D body) + { + Hide(); // Player disappears after being hit. + EmitSignal(nameof(Hit)); + // Must be deferred as we can't change physics properties on a physics callback. + GetNode("CollisionShape2D").SetDeferred("disabled", true); + } + + .. code-tab:: cpp + + // This code goes in `player.cpp`. + void Player::_on_Player_body_entered(godot::Node2D *_body) { + hide(); // Player disappears after being hit. + emit_signal("hit"); + // Must be deferred as we can't change physics properties on a physics callback. + _collision_shape->set_deferred("disabled", true); + } + +Each time an enemy hits the player, the signal is going to be emitted. We need +to disable the player's collision so that we don't trigger the ``hit`` signal +more than once. + +.. Note:: Disabling the area's collision shape can cause an error if it happens + in the middle of the engine's collision processing. Using + ``set_deferred()`` tells Godot to wait to disable the shape until it's + safe to do so. + +The last piece is to add a function we can call to reset the player when +starting a new game. + +.. tabs:: + .. code-tab:: gdscript GDScript + + func start(pos): + position = pos + show() + $CollisionShape2D.disabled = false + + .. code-tab:: csharp + + public void Start(Vector2 pos) + { + Position = pos; + Show(); + GetNode("CollisionShape2D").Disabled = false; + } + + .. code-tab:: cpp + + // This code goes in `player.cpp`. + void Player::start(const godot::Vector2 p_position) { + set_position(p_position); + show(); + _collision_shape->set_disabled(false); + } + +With the player working, we'll work on the enemy in the next lesson. diff --git a/getting_started/first_2d_game/04.creating_the_enemy.rst b/getting_started/first_2d_game/04.creating_the_enemy.rst new file mode 100644 index 000000000..128c0015b --- /dev/null +++ b/getting_started/first_2d_game/04.creating_the_enemy.rst @@ -0,0 +1,180 @@ +.. _doc_your_first_2d_game_creating_the_enemy: + +Creating the enemy +================== + +Now it's time to make the enemies our player will have to dodge. Their behavior +will not be very complex: mobs will spawn randomly at the edges of the screen, +choose a random direction, and move in a straight line. + +We'll create a ``Mob`` scene, which we can then *instance* to create any number +of independent mobs in the game. + +Node setup +~~~~~~~~~~ + +Click Scene -> New Scene and add the following nodes: + +- :ref:`RigidBody2D ` (named ``Mob``) + + - :ref:`AnimatedSprite ` + - :ref:`CollisionShape2D ` + - :ref:`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`` +to ``0``, so the mob will not fall downward. In addition, under the +``PhysicsBody2D`` 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 +player. This time, we have 3 animations: ``fly``, ``swim``, and ``walk``. There +are two images for each animation in the art folder. + +Adjust the "Speed (FPS)" to ``3`` for all animations. + +.. image:: img/mob_animations.gif + +Set the ``Playing`` property in the Inspector to "On". + +We'll select one of these animations randomly so that the mobs will have some +variety. + +Like the player images, these mob images need to be scaled down. Set the +``AnimatedSprite2D``'s ``Scale`` property to ``(0.75, 0.75)``. + +As in the ``Player`` scene, add a ``CapsuleShape2D`` for the collision. To align +the shape with the image, you'll need to set the ``Rotation Degrees`` property +to ``90`` (under "Transform" in the Inspector). + +Save the scene. + +Enemy script +~~~~~~~~~~~~ + +Add a script to the ``Mob`` like this: + +.. tabs:: + .. code-tab:: gdscript GDScript + + extends RigidBody2D + + .. code-tab:: csharp + + public class Mob : RigidBody2D + { + // Don't forget to rebuild the project. + } + + .. code-tab:: cpp + + // Copy `player.gdns` to `mob.gdns` and replace `Player` with `Mob`. + // Attach the `mob.gdns` file to the Mob node. + + // Create two files `mob.cpp` and `mob.hpp` next to `entry.cpp` in `src`. + // This code goes in `mob.hpp`. We also define the methods we'll be using here. + #ifndef MOB_H + #define MOB_H + + #include + #include + #include + + class Mob : public godot::RigidBody2D { + GODOT_CLASS(Mob, godot::RigidBody2D) + + godot::AnimatedSprite2D *_animated_sprite; + + public: + void _init() {} + void _ready(); + void _on_VisibilityNotifier2D_screen_exited(); + + static void _register_methods(); + }; + + #endif // MOB_H + +Now let's look at the rest of the script. In ``_ready()`` we play the animation +and randomly choose one of the three animation types: + +.. tabs:: + .. code-tab:: gdscript GDScript + + func _ready(): + $AnimatedSprite2D.playing = true + var mob_types = $AnimatedSprite2D.frames.get_animation_names() + $AnimatedSprite2D.animation = mob_types[randi() % mob_types.size()] + + .. code-tab:: csharp + + public override void _Ready() + { + var animSprite2D = GetNode("AnimatedSprite2D"); + animSprite2D.Playing = true; + string[] mobTypes = animSprite2D.Frames.GetAnimationNames(); + animSprite2D.Animation = mobTypes[GD.Randi() % mobTypes.Length]; + } + + .. code-tab:: cpp + + // This code goes in `mob.cpp`. + #include "mob.hpp" + + #include + #include + + void Mob::_ready() { + godot::Ref random = godot::RandomNumberGenerator::_new(); + random->randomize(); + _animated_sprite = get_node("AnimatedSprite2D"); + _animated_sprite->_set_playing(true); + godot::PoolStringArray mob_types = _animated_sprite->get_sprite_frames()->get_animation_names(); + _animated_sprite->set_animation(mob_types[random->randi() % mob_types.size()]); + } + +First, we get the list of animation names from the AnimatedSprite2D's ``frames`` +property. This returns an Array containing all three animation names: ``["walk", +"swim", "fly"]``. + +We then need to pick a random number between ``0`` and ``2`` to select one of +these names from the list (array indices start at ``0``). ``randi() % n`` +selects a random integer between ``0`` and ``n-1``. + +.. note:: You must use ``randomize()`` if you want your sequence of "random" + numbers to be different every time you run the scene. We're going to + use ``randomize()`` in our ``Main`` scene, so we won't need it here. + +The last piece is to make the mobs delete themselves when they leave the screen. +Connect the ``screen_exited()`` signal of the ``VisibilityNotifier2D`` node and +add this code: + +.. tabs:: + .. code-tab:: gdscript GDScript + + func _on_VisibilityNotifier2D_screen_exited(): + queue_free() + + .. code-tab:: csharp + + public void OnVisibilityNotifier2DScreenExited() + { + QueueFree(); + } + + .. code-tab:: cpp + + // This code goes in `mob.cpp`. + void Mob::_on_VisibilityNotifier2D_screen_exited() { + queue_free(); + } + +This completes the `Mob` scene. + +With the player and enemies ready, in the next part, we'll bring them together +in a new scene. We'll make enemies spawn randomly around the game board and move +forward, turning our project into a playable game. 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 new file mode 100644 index 000000000..605b40425 --- /dev/null +++ b/getting_started/first_2d_game/05.the_main_game_scene.rst @@ -0,0 +1,446 @@ +.. _doc_your_first_2d_game_the_main_game_scene: + +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``. Ensure you +create a Node, **not** a Node2D. Click the "Instance" button and select your +saved ``Player.tscn``. + +.. image:: img/instance_scene.png + +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 + spawn +- :ref:`Timer ` (named ``ScoreTimer``) - to increment the score + every second +- :ref:`Timer ` (named ``StartTimer``) - to give a delay before + starting +- :ref:`Position2D ` (named ``StartPosition``) - to indicate + the player's start position + +Set the ``Wait Time`` property of each of the ``Timer`` nodes as follows: + +- ``MobTimer``: ``0.5`` +- ``ScoreTimer``: ``1`` +- ``StartTimer``: ``2`` + +In addition, set the ``One Shot`` property of ``StartTimer`` to "On" and set +``Position`` of the ``StartPosition`` node to ``(240, 450)``. + +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 +named ``MobPath`` as a child of ``Main``. When you select ``Path2D``, you will +see some new buttons at the top of the editor: + +.. image:: img/path2d_buttons.png + +Select the middle one ("Add Point") and draw the path by clicking to add the +points at the corners shown. To have the points snap to the grid, make sure "Use +Grid Snap" and "Use Snap" are both selected. These options can be found to the +left of the "Lock" button, appearing as a magnet next to some dots and +intersecting lines, respectively. + +.. image:: img/grid_snap_button.png + +.. important:: Draw the path in *clockwise* order, or your mobs will spawn + pointing *outwards* instead of *inwards*! + +.. image:: img/draw_path2d.gif + +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 ` +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. + +Your scene should look like this: + +.. image:: img/main_scene_nodes.png + +Main script +~~~~~~~~~~~ + +Add a script to ``Main``. At the top of the script, we use ``export +(PackedScene)`` to allow us to choose the Mob scene we want to instance. + +.. tabs:: + .. code-tab:: gdscript GDScript + + extends Node + + export(PackedScene) var mob_scene + var score + + .. code-tab:: csharp + + public class Main : Node + { + // Don't forget to rebuild the project so the editor knows about the new export variable. + + #pragma warning disable 649 + // We assign this in the editor, so we don't need the warning about not being assigned. + [Export] + public PackedScene MobScene; + #pragma warning restore 649 + + public int Score; + } + + .. code-tab:: cpp + + // Copy `player.gdns` to `main.gdns` and replace `Player` with `Main`. + // Attach the `main.gdns` file to the Main node. + + // Create two files `main.cpp` and `main.hpp` next to `entry.cpp` in `src`. + // This code goes in `main.hpp`. We also define the methods we'll be using here. + #ifndef MAIN_H + #define MAIN_H + + #include + #include + #include + #include + #include + #include + #include + #include + + #include "hud.hpp" + #include "player.hpp" + + class Main : public godot::Node { + GODOT_CLASS(Main, godot::Node) + + int score; + HUD *_hud; + Player *_player; + godot::Node2D *_start_position; + godot::PathFollow2D *_mob_spawn_location; + godot::Timer *_mob_timer; + godot::Timer *_score_timer; + godot::Timer *_start_timer; + godot::AudioStreamPlayer *_music; + godot::AudioStreamPlayer *_death_sound; + godot::Ref _random; + + public: + godot::Ref mob_scene; + + void _init() {} + void _ready(); + void game_over(); + void new_game(); + void _on_MobTimer_timeout(); + void _on_ScoreTimer_timeout(); + void _on_StartTimer_timeout(); + + static void _register_methods(); + }; + + #endif // MAIN_H + +We also add a call to ``randomize()`` here so that the random number +generator generates different random numbers each time the game is run: + +.. tabs:: + .. code-tab:: gdscript GDScript + + func _ready(): + randomize() + + .. code-tab:: csharp + + public override void _Ready() + { + GD.Randomize(); + } + + .. code-tab:: cpp + + // This code goes in `main.cpp`. + #include "main.hpp" + + #include + + #include "mob.hpp" + + void Main::_ready() { + _hud = get_node("HUD"); + _player = get_node("Player"); + _start_position = get_node("StartPosition"); + _mob_spawn_location = get_node("MobPath/MobSpawnLocation"); + _mob_timer = get_node("MobTimer"); + _score_timer = get_node("ScoreTimer"); + _start_timer = get_node("StartTimer"); + // Uncomment these after adding the nodes in the "Sound effects" section of "Finishing up". + //_music = get_node("Music"); + //_death_sound = get_node("DeathSound"); + _random = (godot::Ref)godot::RandomNumberGenerator::_new(); + _random->randomize(); + } + +Click the ``Main`` node and you will see the ``Mob Scene`` property in the Inspector +under "Script Variables". + +You can assign this property's value in two ways: + +- Drag ``Mob.tscn`` from the "FileSystem" panel and drop it in the ``Mob`` + property . +- Click the down arrow next to "[empty]" and choose "Load". Select ``Mob.tscn``. + +Next, select the ``Player`` node in the Scene dock, and access the Node dock on +the sidebar. Make sure to have the Signals tab selected in the Node dock. + +You should see a list of the signals for the ``Player`` node. Find and +double-click the ``hit`` signal in the list (or right-click it and select +"Connect..."). This will open the signal connection dialog. We want to make a +new function named ``game_over``, which will handle what needs to happen when a +game ends. Type "game_over" in the "Receiver Method" box at the bottom of the +signal connection dialog and click "Connect". Add the following code to the new +function, as well as a ``new_game`` function that will set everything up for a +new game: + +.. tabs:: + .. code-tab:: gdscript GDScript + + func game_over(): + $ScoreTimer.stop() + $MobTimer.stop() + + func new_game(): + score = 0 + $Player.start($StartPosition.position) + $StartTimer.start() + + .. code-tab:: csharp + + public void GameOver() + { + GetNode("MobTimer").Stop(); + GetNode("ScoreTimer").Stop(); + } + + public void NewGame() + { + Score = 0; + + var player = GetNode("Player"); + var startPosition = GetNode("StartPosition"); + player.Start(startPosition.Position); + + GetNode("StartTimer").Start(); + } + + .. code-tab:: cpp + + // This code goes in `main.cpp`. + void Main::game_over() { + _score_timer->stop(); + _mob_timer->stop(); + } + + void Main::new_game() { + score = 0; + _player->start(_start_position->get_position()); + _start_timer->start(); + } + +Now connect the ``timeout()`` signal of each of the Timer nodes (``StartTimer``, +``ScoreTimer`` , and ``MobTimer``) to the main script. ``StartTimer`` will start +the other two timers. ``ScoreTimer`` will increment the score by 1. + +.. tabs:: + .. code-tab:: gdscript GDScript + + func _on_ScoreTimer_timeout(): + score += 1 + + func _on_StartTimer_timeout(): + $MobTimer.start() + $ScoreTimer.start() + + .. code-tab:: csharp + + public void OnScoreTimerTimeout() + { + Score++; + } + + public void OnStartTimerTimeout() + { + GetNode("MobTimer").Start(); + GetNode("ScoreTimer").Start(); + } + + .. code-tab:: cpp + + // This code goes in `main.cpp`. + void Main::_on_ScoreTimer_timeout() { + score += 1; + } + + void Main::_on_StartTimer_timeout() { + _mob_timer->start(); + _score_timer->start(); + } + + // Also add this to register all methods and the mob scene property. + void Main::_register_methods() { + godot::register_method("_ready", &Main::_ready); + godot::register_method("game_over", &Main::game_over); + godot::register_method("new_game", &Main::new_game); + godot::register_method("_on_MobTimer_timeout", &Main::_on_MobTimer_timeout); + godot::register_method("_on_ScoreTimer_timeout", &Main::_on_ScoreTimer_timeout); + godot::register_method("_on_StartTimer_timeout", &Main::_on_StartTimer_timeout); + godot::register_property("mob_scene", &Main::mob_scene, (godot::Ref)nullptr); + } + +In ``_on_MobTimer_timeout()``, we will create a mob instance, pick a random +starting location along the ``Path2D``, and set the mob in motion. The +``PathFollow2D`` node will automatically rotate as it follows the path, so we +will use that to select the mob's direction as well as its position. +When we spawn a mob, we'll pick a random value between ``150.0`` and +``250.0`` for how fast each mob will move (it would be boring if they were +all moving at the same speed). + +Note that a new instance must be added to the scene using ``add_child()``. + +.. tabs:: + .. code-tab:: gdscript GDScript + + func _on_MobTimer_timeout(): + # Choose a random location on Path2D. + var mob_spawn_location = get_node("MobPath/MobSpawnLocation"); + mob_spawn_location.offset = randi() + + # Create a Mob instance and add it to the scene. + var mob = mob_scene.instance() + add_child(mob) + + # Set the mob's direction perpendicular to the path direction. + var direction = mob_spawn_location.rotation + PI / 2 + + # Set the mob's position to a random location. + mob.position = mob_spawn_location.position + + # Add some randomness to the direction. + direction += rand_range(-PI / 4, PI / 4) + mob.rotation = direction + + # Choose the velocity. + var velocity = Vector2(rand_range(150.0, 250.0), 0.0) + mob.linear_velocity = velocity.rotated(direction) + + .. code-tab:: csharp + + public void OnMobTimerTimeout() + { + // Note: Normally it is best to use explicit types rather than the `var` + // keyword. However, var is acceptable to use here because the types are + // obviously PathFollow2D and Mob, since they appear later on the line. + + // Choose a random location on Path2D. + var mobSpawnLocation = GetNode("MobPath/MobSpawnLocation"); + mobSpawnLocation.Offset = GD.Randi(); + + // Create a Mob instance and add it to the scene. + var mob = (Mob)MobScene.Instance(); + AddChild(mob); + + // Set the mob's direction perpendicular to the path direction. + float direction = mobSpawnLocation.Rotation + Mathf.Pi / 2; + + // Set the mob's position to a random location. + mob.Position = mobSpawnLocation.Position; + + // Add some randomness to the direction. + direction += (float)GD.RandRange(-Mathf.Pi / 4, Mathf.Pi / 4); + mob.Rotation = direction; + + // Choose the velocity. + var velocity = new Vector2((float)GD.RandRange(150.0, 250.0), 0); + mob.LinearVelocity = velocity.Rotated(direction); + } + + .. code-tab:: cpp + + // This code goes in `main.cpp`. + void Main::_on_MobTimer_timeout() { + // Choose a random location on Path2D. + _mob_spawn_location->set_offset((real_t)_random->randi()); + + // Create a Mob instance and add it to the scene. + godot::Node *mob = mob_scene->instance(); + add_child(mob); + + // Set the mob's direction perpendicular to the path direction. + real_t direction = _mob_spawn_location->get_rotation() + (real_t)Math_PI / 2; + + // Set the mob's position to a random location. + mob->set("position", _mob_spawn_location->get_position()); + + // Add some randomness to the direction. + direction += _random->randf_range((real_t)-Math_PI / 4, (real_t)Math_PI / 4); + mob->set("rotation", direction); + + // Choose the velocity for the mob. + godot::Vector2 velocity = godot::Vector2(_random->randf_range(150.0, 250.0), 0.0); + mob->set("linear_velocity", velocity.rotated(direction)); + } + +.. important:: Why ``PI``? In functions requiring angles, Godot uses *radians*, + not degrees. Pi represents a half turn in radians, about + ``3.1415`` (there is also ``TAU`` which is equal to ``2 * PI``). + If you're more comfortable working with degrees, you'll need to + use the ``deg2rad()`` and ``rad2deg()`` functions to convert + between the two. + +Testing the scene +~~~~~~~~~~~~~~~~~ + +Let's test the scene to make sure everything is working. Add this ``new_game`` +call to ``_ready()``: + +.. tabs:: + .. code-tab:: gdscript GDScript + + func _ready(): + randomize() + new_game() + + .. code-tab:: csharp + + public override void _Ready() + { + NewGame(); + } + + .. code-tab:: cpp + + // This code goes in `main.cpp`. + void Main::_ready() { + new_game(); + } + +Let's also assign ``Main`` as our "Main Scene" - the one that runs automatically +when the game launches. Press the "Play" button and select ``Main.tscn`` when +prompted. + +You should be able to move the player around, see mobs spawning, and see the +player disappear when hit by a mob. + +When you're sure everything is working, remove the call to ``new_game()`` from +``_ready()``. + +What's our game lacking? Some user interface. In the next lesson, we'll add a +title screen and display the player's score. diff --git a/getting_started/first_2d_game/06.heads_up_display.rst b/getting_started/first_2d_game/06.heads_up_display.rst new file mode 100644 index 000000000..87f850320 --- /dev/null +++ b/getting_started/first_2d_game/06.heads_up_display.rst @@ -0,0 +1,437 @@ +.. _doc_your_first_2d_game_heads_up_display: + +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 +``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 +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. + +The HUD needs to display the following information: + +- Score, changed by ``ScoreTimer``. +- 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 `. + +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``. + +Click on the ``ScoreLabel`` and type a number into the ``Text`` field in the +Inspector. The default font for ``Control`` nodes is small and doesn't scale +well. There is a font file included in the game assets called +"Xolonium-Regular.ttf". To use this font, do the following: + +1. Under "Custom Fonts", choose "New Font" + +.. image:: img/custom_font1.png + +2. Click on the "Font" you added, and under "Font/Data/0", + choose "Load" and select the "Xolonium-Regular.ttf" file. + +.. image:: img/custom_font2.png + +Once you've done this on the ``ScoreLabel``, you can click the down arrow next +to the Font property and choose "Copy", then "Paste" it in the same place +on the other two Control nodes. +Set "Custom Font Size" property of the ``ScoreLabel``. A setting of ``64`` works well. + +.. image:: img/custom_font3.png + +.. note:: **Anchors and Margins:** ``Control`` nodes have a position and size, + but they also have anchors and margins. Anchors define the origin - + the reference point for the edges of the node. Margins update + automatically when you move or resize a control node. They represent + the distance from the control node's edges to its anchor. + +Arrange the nodes as shown below. Click the "Layout" button to set a Control +node's layout: + +.. image:: img/ui_anchor.png + +You can drag the nodes to place them manually, or for more precise placement, +use the following settings: + +ScoreLabel +~~~~~~~~~~ + +- *Layout* : "Top Wide" +- *Text* : ``0`` +- *Align* : "Center" + +Message +~~~~~~~~~~~~ + +- *Layout* : "HCenter Wide" +- *Text* : ``Dodge the Creeps!`` +- *Align* : "Center" +- *Autowrap* : "On" + +StartButton +~~~~~~~~~~~ + +- *Text* : ``Start`` +- *Layout* : "Center Bottom" +- *Margin* : + + - Top: ``-200`` + - Bottom: ``-100`` + +On the ``MessageTimer``, set the ``Wait Time`` to ``2`` and set the ``One Shot`` +property to "On". + +Now add this script to ``HUD``: + +.. tabs:: + .. code-tab:: gdscript GDScript + + extends CanvasLayer + + signal start_game + + .. code-tab:: csharp + + public class HUD : CanvasLayer + { + // Don't forget to rebuild the project so the editor knows about the new signal. + + [Signal] + public delegate void StartGame(); + } + + .. code-tab:: cpp + + // Copy `player.gdns` to `hud.gdns` and replace `Player` with `HUD`. + // Attach the `hud.gdns` file to the HUD node. + + // Create two files `hud.cpp` and `hud.hpp` next to `entry.cpp` in `src`. + // This code goes in `hud.hpp`. We also define the methods we'll be using here. + #ifndef HUD_H + #define HUD_H + + #include + #include + #include + #include + #include + + class HUD : public godot::CanvasLayer { + GODOT_CLASS(HUD, godot::CanvasLayer) + + godot::Label *_score_label; + godot::Label *_message_label; + godot::Timer *_start_message_timer; + godot::Timer *_get_ready_message_timer; + godot::Button *_start_button; + godot::Timer *_start_button_timer; + + public: + void _init() {} + void _ready(); + void show_get_ready(); + void show_game_over(); + void update_score(const int score); + void _on_StartButton_pressed(); + void _on_StartMessageTimer_timeout(); + void _on_GetReadyMessageTimer_timeout(); + + static void _register_methods(); + }; + + #endif // HUD_H + +The ``start_game`` signal tells the ``Main`` node that the button +has been pressed. + +.. tabs:: + .. code-tab:: gdscript GDScript + + func show_message(text): + $Message.text = text + $Message.show() + $MessageTimer.start() + + .. code-tab:: csharp + + public void ShowMessage(string text) + { + var message = GetNode