diff --git a/README.md b/README.md index 56ff65bf5..b4a63268b 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ They are meant to be parsed with the [Sphinx](https://www.sphinx-doc.org/) docum **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 arguably less convenient to edit than a wiki, this git repository is meant to receive pull requests to always improve the documentation, add new pages, etc. Having direct access to the source files in a revision control system is a big plus to ensure the quality of our documentation. +Though arguably less convenient to edit than a wiki, this Git repository is meant to receive pull requests to always improve the documentation, add new pages, etc. Having direct access to the source files in a revision control system is a big plus to ensure the quality of our documentation. ### Editing existing pages diff --git a/_static/css/custom.css b/_static/css/custom.css index c18d4a58f..528222fc7 100644 --- a/_static/css/custom.css +++ b/_static/css/custom.css @@ -212,6 +212,14 @@ legend, opacity: 0.75; } +.rst-content div.figure.figure-w480 { + max-width: 480px; +} + +.rst-content div.figure img { + border: 1px solid var(--body-color); +} + p, article ul, article ol, diff --git a/community/contributing/bug_triage_guidelines.rst b/community/contributing/bug_triage_guidelines.rst index c64882b8b..4aac5aa6f 100644 --- a/community/contributing/bug_triage_guidelines.rst +++ b/community/contributing/bug_triage_guidelines.rst @@ -62,7 +62,7 @@ The following labels are currently defined in the Godot repository: - *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. +- *Needs rebase*: the issue need a Git rebase to 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 diff --git a/community/contributing/pr_workflow.rst b/community/contributing/pr_workflow.rst index 916fe10f6..4f6ed7b8a 100644 --- a/community/contributing/pr_workflow.rst +++ b/community/contributing/pr_workflow.rst @@ -255,7 +255,7 @@ You would then do your changes to our example's (text editor, IDE, etc.). By default, those changes are *unstaged*. The staging area is a layer between -your working directory (where you make your modifications) and the local git +your working directory (where you make your modifications) and the local Git repository (the commits and all the metadata in the ``.git`` folder). To bring changes from the working directory to the Git repository, you need to *stage* them with the ``git add`` command, and then to commit them with the diff --git a/community/contributing/updating_the_class_reference.rst b/community/contributing/updating_the_class_reference.rst index 5d60132e1..dad35ffc4 100644 --- a/community/contributing/updating_the_class_reference.rst +++ b/community/contributing/updating_the_class_reference.rst @@ -39,7 +39,7 @@ There are 5 steps to update the class reference (full guide below): Get started with GitHub ----------------------- -If you're new to git and GitHub, this guide will help you get started. You'll learn to: +If you're new to Git and GitHub, this guide will help you get started. You'll learn to: - Fork and clone Godot's repository - Keep your fork up to date with other contributors @@ -83,7 +83,7 @@ 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: +You should have two: ``origin``, your fork on GitHub that Git adds by default, and ``upstream``, that you just added: :: @@ -119,7 +119,7 @@ Another option is to delete the branch you're working on, synchronize the master 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. +If you're feeling lost by now, come to our `IRC channels `_ and ask for help. Experienced Git users will give you a hand. Updating the documentation template ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/community/contributing/ways_to_contribute.rst b/community/contributing/ways_to_contribute.rst index fcd069131..11875f8fc 100644 --- a/community/contributing/ways_to_contribute.rst +++ b/community/contributing/ways_to_contribute.rst @@ -63,7 +63,7 @@ As such, everyone is entitled to modify modifications back to the upstream project in the form of a patch (a text file describing the changes in a ready-to-apply manner) or - in the modern workflow that we use - via a so-called "pull request" (PR), i.e. a proposal to directly -merge one or more git commits (patches) into the main development branch. +merge one or more Git commits (patches) into the main development branch. Contributing code changes upstream has two big advantages: @@ -77,12 +77,12 @@ Contributing code changes upstream has two big advantages: - The whole community will benefit from your work, and other contributors will behave the same way, contributing code that will be beneficial to you. At - the time of this writing, more than 300 developers have contributed code + the time of this writing, more than 1000 developers have contributed code changes to the engine! To ensure good collaboration and overall quality, the Godot developers enforce some rules for code contributions, for example regarding the style to -use in the C++ code (indentation, brackets, etc.) or the git and PR workflow. +use in the C++ code (indentation, brackets, etc.) or the Git and PR workflow. A good place to start is by searching for issues tagged as `junior jobs `_ (or `Hacktoberfest `_ during October) on GitHub. @@ -181,7 +181,7 @@ There are two separate resources referred to as "documentation" in Godot: 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. + `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 tutorials and engine documentation and its translations.** This is the part you are reading diff --git a/development/compiling/introduction_to_the_buildsystem.rst b/development/compiling/introduction_to_the_buildsystem.rst index 453bec226..d408098b1 100644 --- a/development/compiling/introduction_to_the_buildsystem.rst +++ b/development/compiling/introduction_to_the_buildsystem.rst @@ -182,6 +182,36 @@ This flag appends ``.32`` or ``.64`` suffixes to resulting binaries when relevant. If ``bits=default`` is used, the suffix will match the detected architecture. +.. _doc_buildsystem_custom_modules: + +Custom modules +-------------- + +It's possible to compile modules residing outside of Godot's directory +tree, along with the built-in modules. + +A ``custom_modules`` build option can be passed to the command line before +compiling. The option represents a comma-separated list of directory paths +containing a collection of independent C++ modules that can be seen as C++ +packages, just like the built-in ``modules/`` directory. + +For instance, it's possible to provide both relative, absolute, and user +directory paths containing such modules: + +:: + + scons custom_modules="../modules,/abs/path/to/modules,~/src/godot_modules" + +.. note:: + + If there's any custom module with the exact directory name as a built-in + module, the engine will only compile the custom one. This logic can be used + to override built-in module implementations. + +.. seealso:: + + :ref:`doc_custom_modules_in_c++` + Other build options ------------------- @@ -206,7 +236,7 @@ source to initialize any SCons build options passed via the command line: .. code-block:: python # custom.py - + optimize = "size" module_mono_enabled = "yes" use_llvm = "yes" diff --git a/development/cpp/configuring_an_ide/android_studio.rst b/development/cpp/configuring_an_ide/android_studio.rst index e5c43018f..7e8419331 100644 --- a/development/cpp/configuring_an_ide/android_studio.rst +++ b/development/cpp/configuring_an_ide/android_studio.rst @@ -8,12 +8,19 @@ Android Studio It has a feature-rich editor which supports Java and C/C++. It can be used to work on Godot's core engine as well as the Android platform codebase. -- From Android Studio's welcome window, select - **Open an existing Android Studio project**. +Importing the project +--------------------- -.. image:: img/android_studio_setup_project_1.png +- From the Android Studio's welcome window select **Open an existing + Android Studio project**. -- Navigate to ``/platform/android/java`` and select the ``settings.gradle`` gradle file. +.. figure:: img/android_studio_setup_project_1.png + :figclass: figure-w480 + :align: center + + Android Studio's welcome window. + +- Navigate to ``/platform/android/java`` and select the ``settings.gradle`` file. - Android Studio will import and index the project. - To build the project, follow the :ref:`compiling instructions `. diff --git a/development/cpp/configuring_an_ide/clion.rst b/development/cpp/configuring_an_ide/clion.rst index f63e54362..874cf2ca9 100644 --- a/development/cpp/configuring_an_ide/clion.rst +++ b/development/cpp/configuring_an_ide/clion.rst @@ -3,29 +3,39 @@ CLion ===== -`CLion `_ is a commercial IDE for C++. -It requires a ``CMakeLists.txt`` file as a project file, which is problematic -for Godot which uses the SCons buildsystem instead of CMake. -However, there is a ``CMakeLists.txt`` configuration for -:ref:`Android Studio ` which can also -be used by CLion. +`CLion `_ is a commercial +`JetBrains `_ IDE for C++. -- If you've already opened another project, choose **File > Open** at the top of - the CLion window. Otherwise, choose the option to import an existing project - in the Welcome window. -- Navigate to your Godot Git clone then select the folder - ``platform/android/java/lib`` - the ``CMakeLists.txt`` file is located there. - Select the folder (*not* the ``CMakeLists.txt file``), then click **OK**. +Importing the project +--------------------- -.. image:: img/clion_1_open.png +CLion requires a ``CMakeLists.txt`` file as a project file, which is problematic +for Godot because it uses the SCons buildsystem instead of CMake. However, +there is a ``CMakeLists.txt`` configuration for :ref:`Android Studio ` +which can also be used by CLion. + +- From the CLion's welcome window choose the option to import an existing + project. If you've already opened another project, choose **File > Open** + from the top menu. +- Navigate to ``/platform/android/java/lib`` (the + ``CMakeLists.txt`` file is located there) and select it (but *not* the + ``CMakeLists.txt`` file itself), then click **OK**. + +.. figure:: img/clion_1_open.png + :align: center + + The folder containing the ``CMakeLists.txt`` file. - If this popup window appears, select **This Window** to open the project: -.. image:: img/clion_2_this_window.png +.. figure:: img/clion_2_this_window.png + :align: center -- Choose **Tools > CMake >Change Project Root** and select the root Godot folder. +- Choose **Tools > CMake > Change Project Root** from the top menu and select + the Godot root folder. -.. image:: img/clion_3_change_project_root.png +.. figure:: img/clion_3_change_project_root.png + :align: center - You should be now be able to see all the project files. Autocomplete should work once the project has finished indexing. diff --git a/development/cpp/configuring_an_ide/img/qtcreator-add-custom-process-step.png b/development/cpp/configuring_an_ide/img/qtcreator-add-custom-process-step.png deleted file mode 100644 index cc4bd260d..000000000 Binary files a/development/cpp/configuring_an_ide/img/qtcreator-add-custom-process-step.png and /dev/null differ diff --git a/development/cpp/configuring_an_ide/img/qtcreator-edit-files-dialog.png b/development/cpp/configuring_an_ide/img/qtcreator-edit-files-dialog.png deleted file mode 100644 index dd15c2ac7..000000000 Binary files a/development/cpp/configuring_an_ide/img/qtcreator-edit-files-dialog.png and /dev/null differ diff --git a/development/cpp/configuring_an_ide/img/vs_2_project_properties.png b/development/cpp/configuring_an_ide/img/vs_2_project_properties.png index f61dd9041..a0fc1d883 100644 Binary files a/development/cpp/configuring_an_ide/img/vs_2_project_properties.png and b/development/cpp/configuring_an_ide/img/vs_2_project_properties.png differ diff --git a/development/cpp/configuring_an_ide/img/vscode_1_create_launch.json.png b/development/cpp/configuring_an_ide/img/vscode_1_create_launch.json.png index 2e9e1761d..80bde1507 100644 Binary files a/development/cpp/configuring_an_ide/img/vscode_1_create_launch.json.png and b/development/cpp/configuring_an_ide/img/vscode_1_create_launch.json.png differ diff --git a/development/cpp/configuring_an_ide/img/vscode_configure_task.png b/development/cpp/configuring_an_ide/img/vscode_configure_task.png new file mode 100644 index 000000000..f69e76b7f Binary files /dev/null and b/development/cpp/configuring_an_ide/img/vscode_configure_task.png differ diff --git a/development/cpp/configuring_an_ide/img/vscode_create_tasksjson.png b/development/cpp/configuring_an_ide/img/vscode_create_tasksjson.png new file mode 100644 index 000000000..bfc9903c4 Binary files /dev/null and b/development/cpp/configuring_an_ide/img/vscode_create_tasksjson.png differ diff --git a/development/cpp/configuring_an_ide/img/vscode_create_tasksjson_others.png b/development/cpp/configuring_an_ide/img/vscode_create_tasksjson_others.png new file mode 100644 index 000000000..fa7b50944 Binary files /dev/null and b/development/cpp/configuring_an_ide/img/vscode_create_tasksjson_others.png differ diff --git a/development/cpp/configuring_an_ide/index.rst b/development/cpp/configuring_an_ide/index.rst index b47287a16..f13fda380 100644 --- a/development/cpp/configuring_an_ide/index.rst +++ b/development/cpp/configuring_an_ide/index.rst @@ -16,8 +16,8 @@ Development Environment), here are setup instructions for some popular ones: clion kdevelop qt_creator - visual_studio_code visual_studio + visual_studio_code xcode It is possible to use other IDEs, but their setup is not documented yet. diff --git a/development/cpp/configuring_an_ide/kdevelop.rst b/development/cpp/configuring_an_ide/kdevelop.rst index 6b79bf1ba..914e29a2c 100644 --- a/development/cpp/configuring_an_ide/kdevelop.rst +++ b/development/cpp/configuring_an_ide/kdevelop.rst @@ -5,54 +5,83 @@ KDevelop `KDevelop `_ is a free, open source IDE for all desktop platforms. -Start by opening KDevelop and choosing **Open Project**. +Importing the project +--------------------- -.. image:: img/kdevelop_newproject.png +- From the KDevelop's main screen select **Open Project**. -Choose the directory where you cloned Godot. +.. figure:: img/kdevelop_newproject.png + :figclass: figure-w480 + :align: center -On the next screen, choose **Custom Build System** for the **Project Manager**. + KDevelop's main screen. -.. image:: img/kdevelop_custombuild.png +- Navigate to the Godot root folder and select it. +- On the next screen, choose **Custom Build System** for the **Project Manager**. -Now that the project has been imported, open the project configuration. +.. figure:: img/kdevelop_custombuild.png + :figclass: figure-w480 + :align: center -.. image:: img/kdevelop_openconfig.png +- After the project has been imported, open the project configuration by right-clicking + on it in the **Projects** panel and selecting **Open Configuration..** option. -Add the following includes/imports: +.. figure:: img/kdevelop_openconfig.png + :figclass: figure-w480 + :align: center -.. code-block:: none +- Under **Language Support** open the **Includes/Imports** tab and add the following paths: - . // a dot to indicate the root of the Godot project - core/ - core/os/ - core/math/ - drivers/ - platform/linuxbsd/ // make that platform/osx/ if you're using macOS + .. code-block:: none -.. image:: img/kdevelop_addincludes.png + . // A dot, to indicate the root of the Godot project + core/ + core/os/ + core/math/ + drivers/ + platform// // Replace with a folder + corresponding to your current platform -Apply the changes. +.. figure:: img/kdevelop_addincludes.png + :figclass: figure-w480 + :align: center -Switch to the **Custom Build System** tab. Add a build configuration -and keep the build directory blank. Enable build tools and add ``scons`` -as the executable then add ``platform=linuxbsd target=debug`` (``platform=osx`` -if you're on macOS) as the arguments. +- Apply the changes. +- Under **Custom Build System** add a new build configuration with the following settings: -.. image:: img/kdevelop_buildconfig.png + +-----------------+------------------------------------------------------------------------------+ + | Build Directory | *blank* | + +-----------------+------------------------------------------------------------------------------+ + | Enable | **True** | + +-----------------+------------------------------------------------------------------------------+ + | Executable | **scons** | + +-----------------+------------------------------------------------------------------------------+ + | Arguments | See :ref:`doc_introduction_to_the_buildsystem` for a full list of arguments. | + +-----------------+------------------------------------------------------------------------------+ -Next, we need to tell KDevelop where to find the binary. -From the **Run** menu, choose **Configure Launches**. +.. figure:: img/kdevelop_buildconfig.png + :figclass: figure-w480 + :align: center -.. image:: img/kdevelop_configlaunches.png +- Apply the changes and close the configuration window. -Click **Add** if no launcher exists. Then add the path to your -executable in the executable section. Your executable should be located -in the ``bin/`` subdirectory and should be named something like -``godot.linuxbsd.tools.64`` (the name could be different depending on your -platform and build options). +Debugging the project +--------------------- -.. image:: img/kdevelop_configlaunches2.png +- Select **Run > Configure Launches...** from the top menu. + +.. figure:: img/kdevelop_configlaunches.png + :figclass: figure-w480 + :align: center + +- Click **Add** to create a new launch configuration. +- Select **Executable** option and specify the path to your executable located in + the ``/bin`` folder. The name depends on your build configuration, + e.g. ``godot.x11.tools.64`` for 64-bit X11 platform with ``tools`` enabled. + +.. figure:: img/kdevelop_configlaunches2.png + :figclass: figure-w480 + :align: center If you run into any issues, ask for help in one of `Godot's community channels `__. diff --git a/development/cpp/configuring_an_ide/qt_creator.rst b/development/cpp/configuring_an_ide/qt_creator.rst index 62d208db5..d79e5b847 100644 --- a/development/cpp/configuring_an_ide/qt_creator.rst +++ b/development/cpp/configuring_an_ide/qt_creator.rst @@ -3,103 +3,109 @@ Qt Creator ========== -Qt Creator is a free, open source IDE for all desktop platforms. +`Qt Creator `_ is a free, open source IDE for all desktop platforms. Importing the project --------------------- -- Choose **New Project > Import Project > Import Existing Project**. +- From the Qt Creator's main screen select **New Project > Import Project > Import Existing Project**. -.. image:: img/qtcreator-new-project.png +.. figure:: img/qtcreator-new-project.png + :figclass: figure-w480 + :align: center -- Set the path to your Godot root directory and enter the project name. +- Under **Location** select the Godot root folder. -.. image:: img/qtcreator-set-project-path.png +.. figure:: img/qtcreator-set-project-path.png + :figclass: figure-w480 + :align: center -- Here you can choose which folders and files will be visible to the project. - C/C++ files are added automatically. Potentially useful additions: +- Next, you can choose which folders and files will be visible to the project. + While C/C++ files are added automatically, other extensions can be potentially useful: ``*.py`` for buildsystem files, ``*.java`` for Android platform development, - ``*.mm`` for macOS platform development. Click **Next**. + ``*.mm`` for macOS platform development. -.. image:: img/qtcreator-apply-import-filter.png +.. figure:: img/qtcreator-apply-import-filter.png + :figclass: figure-w480 + :align: center -- Click **Finish**. -- Add a line containing ``.`` to ``project_name.includes`` to get working - code completion. +.. note:: You can change this configuration later by right-clicking on your project + and selecting the **Edit Files...** option. -.. image:: img/qtcreator-project-name-includes.png + .. figure:: img/qtcreator-edit-files-menu.png + :figclass: figure-w480 + :align: center -Build and run --------------- -Build configuration: +- Finish the import. +- Open the ``project_name.includes`` file and add a line containing ``.`` to it + to correctly enable the code completion. -- Click on **Projects** and open the **Build** tab. +.. figure:: img/qtcreator-project-name-includes.png + :figclass: figure-w480 + :align: center + +- From the left-side menu select **Projects** and open the **Build** tab. - Delete the predefined ``make`` build step. -.. image:: img/qtcreator-projects-build.png +.. figure:: img/qtcreator-projects-build.png + :figclass: figure-w480 + :align: center -- Click **Add Build Step > Custom Process Step**. +- Click **Add Build Step > Custom Process Step** to add a new build step + with the following settings: -.. image:: img/qtcreator-add-custom-process-step.png + +-----------+------------------------------------------------------------------------------+ + | Command | **scons** | + +-----------+------------------------------------------------------------------------------+ + | Arguments | See :ref:`doc_introduction_to_the_buildsystem` for a full list of arguments. | + +-----------+------------------------------------------------------------------------------+ -- Type ``scons`` in the **Command** field. If it fails with - ``Could not start process "scons"``, it can mean that ``scons`` is not in - your ``PATH`` environment variable. In this case, you'll have to specify the - full path to the SCons binary. -- Fill the **Arguments** field with your compilation options - (e.g.: ``p=linuxbsd target=debug -j 4``). +.. figure:: img/qtcreator-set-scons-command.png + :figclass: figure-w480 + :align: center -.. image:: img/qtcreator-set-scons-command.png +.. note:: If the build fails with ``Could not start process "scons"``, it can mean that ``scons`` + is not in your ``PATH`` environment variable. In this case, you'll have to specify the + full path to the SCons binary. -Run configuration: +Debugging the project +--------------------- -- Open the **Run** tab. -- Point the **Executable** to your compiled Godot binary - (e.g: ``%{buildDir}/bin/godot.linuxbsd.opt.tools.64``). -- If you want to run a specific project, point **Working directory** to the - project folder. -- If you want to run the editor, add ``-e`` to the **Command line arguments** - field. +- From the left-side menu select **Projects** and open the **Run** tab. +- Under **Executable** specify the path to your executable located in + the ``/bin`` folder. The name depends on your build configuration, + e.g. ``godot.x11.tools.64`` for 64-bit X11 platform with ``tools`` enabled. + You can use ``%{buildDir}`` to reference the project root, e.g: ``%{buildDir}/bin/godot.x11.opt.tools.64``. +- If you want to run a specific project, specify its root folder under **Working directory**. +- If you want to run the editor, add ``-e`` to the **Command line arguments** field. -.. image:: img/qtcreator-run-command.png +.. figure:: img/qtcreator-run-command.png + :figclass: figure-w480 + :align: center -Updating sources after pulling latest commits ---------------------------------------------- - -As a developer, you usually want to frequently pull the latest commits from the -upstream Git repository or a specific fork. However, this brings a problem with -it: as the development continues, source files (and folders) are added or -removed. These changes need to be reflected in your project files for Qt Creator -too, so you continue to have a nice programming experience. A simple way to -check is to right click at your root folder in the **Projects View** and click -on **Edit files...**. - -.. image:: img/qtcreator-edit-files-menu.png - -Now a new dialog should appear that is similar in functionality to the one in -the third step of the *Importing the project* section above. Here, you can check -whether you want to add/remove specific files and/or folders. You can choose by -clicking with your mouse or just simply by clicking the **Apply Filter** button. -Click on **OK** and you're ready to continue working. - -.. image:: img/qtcreator-edit-files-dialog.png +To learn more about command line arguments, refer to the +:ref:`command line tutorial `. Code style configuration ------------------------ Developers must follow the project's :ref:`code style ` -and the IDE should help them follow it. By default, Qt Creator does use spaces +and the IDE should help them follow it. By default, Qt Creator uses spaces for indentation which doesn't match the Godot code style guidelines. You can change this behavior by changing the **Code Style** in **Options > C++**. -.. image:: img/qtcreator-options-cpp.png +.. figure:: img/qtcreator-options-cpp.png + :figclass: figure-w480 + :align: center Click on **Edit** to change the current settings, then click on **Copy Built-in Code Style** button to set a new code style. Set a name for it (e.g. Godot) and change the Tab policy to be **Tabs Only**. -.. image:: img/qtcreator-edit-codestyle.png +.. figure:: img/qtcreator-edit-codestyle.png + :figclass: figure-w480 + :align: center If you run into any issues, ask for help in one of `Godot's community channels `__. diff --git a/development/cpp/configuring_an_ide/visual_studio.rst b/development/cpp/configuring_an_ide/visual_studio.rst index 67db5400f..4a46351ff 100644 --- a/development/cpp/configuring_an_ide/visual_studio.rst +++ b/development/cpp/configuring_an_ide/visual_studio.rst @@ -3,62 +3,66 @@ Visual Studio ============= -Visual Studio Community is a Windows-only IDE that's free for non-commercial use. +`Visual Studio Community `__ is a Windows-only IDE +by `Microsoft `_ that's free for non-commercial use. It has many useful features, such as memory view, performance view, source -control and more. You can get it -`from Microsoft `__. +control and more. -Setup ------ +Importing the project +--------------------- -To start developing with Visual Studio, follow these steps: +Visual Studio requires a solution file to work on a project. While Godot does not come +with the solution file, it can be generated using SCons. -- Open the Visual Studio Installer and install the C++ package: +- Navigate to the Godot root folder and open a Command Prompt or PowerShell window. +- Run ``scons platform=windows vsproj=yes`` to generate the solution. +- You can now open the project by double-clicking on the ``godot.sln`` in the project root + or by using the **Open a project or solution** option inside of the Visual Studio. +- Use the **Build** top menu to build the project. -.. image:: img/vs_1_install_cpp_package.png +.. warning:: Visual Studio must be configured with the C++ package. It can be selected + in the intaller: -- Open a Command Prompt or PowerShell window, use ``cd`` to reach the Godot source - directory and run ``scons platform=windows vsproj=yes``. + .. figure:: img/vs_1_install_cpp_package.png + :align: center -- Now open the Godot folder by clicking **Open a project or solution** and choose - ``godot.sln``. - - You can also double-click the ``godot.sln`` file in Explorer. - -You can now start developing with Visual Studio. - -Debugging ---------- +Debugging the project +--------------------- Visual Studio features a powerful debugger. This allows the user to examine Godot's -source code, stop at specific points in the code, make changes, and view them on the run. +source code, stop at specific points in the code, inspect the current execution context, +and make live changes to the codebase. -.. note:: Debugging the Godot Engine inside the editor will require an extra setup step. +You can launch the project with the debugger attached using the **Debug > Start Debugging** +option from the top menu. However, unless you want to debug the project manager specifically, +you'd need to configure debugging options first. This is due to the fact that when the Godot +project manager opens a project, the initial process is terminated and the debugger gets detached. - Because opening Godot opens the Project Manager at first instead of the project - you're working on, the debugger will detach as soon as you open a project. - This means that the debugger will stop, even though Godot is still running in - another process. +- To configure the launch options to use with the debugger use **Project > Properties** + from the top menu: -To overcome this, you need to edit the debugging command line arguments in VS. In your -project, click **Project > Project Properties**: +.. figure:: img/vs_2_project_properties.png + :align: center -.. image:: img/vs_2_project_properties.png +- Open the **Debugging** section and under **Command Arguments** add two new arguments: + the ``-e`` flag opens the editor instead of the project manager, and the ``--path`` argument + tells the executable to open the specified project (must be provided as an *absolute* path + to the project root, not the ``project.godot`` file). -Then add this to the command arguments: - -.. image:: img/vs_3_debug_command_line.png - -- The ``-e`` flag is for entering the editor directly (which skips the Project Manager). -- The ``--path`` argument should be an *absolute* path to a project directory (not a - `project.godot` file). +.. figure:: img/vs_3_debug_command_line.png + :align: center To learn more about command line arguments, refer to the :ref:`command line tutorial `. -To check that everything is working, put a breakpoint in ``main.cpp`` and press F5 to +Even if you start the project without a debugger attached it can still be connected to the running +process using **Debug > Attach to Process...** menu. + +To check that everything is working, put a breakpoint in ``main.cpp`` and press :kbd:`F5` to start debugging. -.. image:: img/vs_4_debugging_main.png +.. figure:: img/vs_4_debugging_main.png + :align: center If you run into any issues, ask for help in one of `Godot's community channels `__. diff --git a/development/cpp/configuring_an_ide/visual_studio_code.rst b/development/cpp/configuring_an_ide/visual_studio_code.rst index ac3d67f5a..2f6281d96 100644 --- a/development/cpp/configuring_an_ide/visual_studio_code.rst +++ b/development/cpp/configuring_an_ide/visual_studio_code.rst @@ -3,47 +3,104 @@ Visual Studio Code ================== -Visual Studio Code is a free cross-platform IDE (not to be confused with -:ref:`doc_configuring_an_ide_vs`). You can get it -`from Microsoft `__. +`Visual Studio Code `_ is a free cross-platform IDE +by `Microsoft `_ (not to be confused with :ref:`doc_configuring_an_ide_vs`). +Importing the project +--------------------- - Make sure the C/C++ extension is installed. You can find instructions in - the `documentation `_. -- Open the cloned Godot folder in Visual Studio Code with + the `official documentation `_. +- From the Visual Studio Code's main screen open the Godot root folder with **File > Open Folder...**. +- Press :kbd:`Ctrl + Shift + P` to open the command prompt window and enter *Configure Task*. -In order to build the project, you need two configuration files: -``launch.json`` and ``tasks.json``. To create them: +.. figure:: img/vscode_configure_task.png + :align: center -- Open the **Debug** view by pressing :kbd:`Ctrl + Shift + D` and select the - cogwheel with an orange dot: +- Select the **Create tasks.json file from template** option. -.. image:: img/vscode_1_create_launch.json.png +.. figure:: img/vscode_create_tasksjson.png + :align: center -- Select **C++ (GDB/LLDB)** (it might be named differently on macOS or Windows). +- Then select **Others**. -- Update ``launch.json`` to match: +.. figure:: img/vscode_create_tasksjson_others.png + :align: center -.. image:: img/vscode_2_launch.json.png +- Within the ``tasks.json`` file find the ``"tasks"`` array and add a new section to it: -If you're following this guide on macOS or Windows, you will have to adjust -``godot.linuxbsd.tools.64`` accordingly. +.. code-block:: js -- Create a ``tasks.json`` file by starting the Debug process with :kbd:`F5`. - Visual Studio Code will show a dialog with a **Configure Task** button. - Choose it and select **Create tasks.json file from template**, then select **Others**. + { + "label": "build", + "type": "shell", + "command": "scons", + "group": "build", + "args": [ + "platform=x11", // Change to your current platform + "target=debug", + "-j4" + ], + "problemMatcher": "$msCompile" + } -- Update ``tasks.json`` to match: +.. figure:: img/vscode_3_tasks.json.png + :figclass: figure-w480 + :align: center -.. image:: img/vscode_3_tasks.json.png + An example of a filled out ``tasks.json``. -If you're following this guide on macOS or Windows, you will have to adjust -``platform=linuxbsd`` accordingly. +Arguments are can be different based on your own setup and needs. See +:ref:`doc_introduction_to_the_buildsystem` for a full list of arguments. -- You can now start the Debug process again to test that everything works. -- If the build phase fails, check the console for hints. On Linux, it's most - likely due to missing dependencies. Check :ref:`doc_compiling_for_linuxbsd`. +Debugging the project +--------------------- + +To run and debug the project you need to create a new configuration in the ``launch.json`` file. + +- Press :kbd:`Ctrl + Shift + D` to open the Run panel. +- If ``launch.json`` file is missing you will be prompted to create a new one. + +.. figure:: img/vscode_1_create_launch.json.png + :align: center + +- Select **C++ (GDB/LLDB)**. There may be another platform specific option here. If selected, + adjust the configuration example provided accordingly. +- Within the ``launch.json`` file find the ``"configurations"`` array and add a new section to it: + +.. code-block:: js + + { + "name": "Launch", + "type": "cppdbg", + "request": "launch", + "program": "${workspaceFolder}/bin/godot.x11.tools.64", + // Change to your current platform + "args": [ "-e" ], + "stopAtEntry": false, + "cwd": "${workspaceFolder}", + "environment": [], + "externalConsole": true, + "MIMode": "gdb", + "setupCommands": [ + { + "description": "Enable pretty-printing for gdb", + "text": "-enable-pretty-printing", + "ignoreFailures": true + } + ], + "preLaunchTask": "build" + } + +.. figure:: img/vscode_2_launch.json.png + :figclass: figure-w480 + :align: center + + An example of a filled out ``launch.json``. + +The name under ``program`` depends on your build configuration, +e.g. ``godot.x11.tools.64`` for 64-bit X11 platform with ``tools`` enabled. If you run into any issues, ask for help in one of `Godot's community channels `__. diff --git a/development/cpp/configuring_an_ide/xcode.rst b/development/cpp/configuring_an_ide/xcode.rst index 305b9968d..4fcf4ccf0 100644 --- a/development/cpp/configuring_an_ide/xcode.rst +++ b/development/cpp/configuring_an_ide/xcode.rst @@ -3,93 +3,108 @@ Xcode ===== -Xcode is a free macOS-only IDE. You can download it from the Mac App Store. +`Xcode `_ is a free macOS-only IDE. You can +download it from the Mac App Store. -Project setup -------------- +Importing the project +--------------------- -- Create an Xcode external build project anywhere. +- From Xcode's main screen create a new project using the **Other > External Build System** template. -.. image:: img/xcode_1_create_external_build_project.png +.. figure:: img/xcode_1_create_external_build_project.png + :figclass: figure-w480 + :align: center -Go to the build target's **Info** tab, then: +- Open your build targets from the **Targets** section and select the **Info** tab. +- Fill out the form with the following settings: -- Set **Build Tool** to the full path to SCons. -- Set **Arguments** to something like - ``platform=osx tools=yes bits=64 target=debug``. -- Set **Directory** to the path to Godot's source folder. -- You may uncheck **Pass build settings in environment**. + +------------+------------------------------------------------------------------------------+ + | Build Tool | A full path to the **scons** executable, e.g. **/usr/local/bin/scons** | + +------------+------------------------------------------------------------------------------+ + | Arguments | See :ref:`doc_introduction_to_the_buildsystem` for a full list of arguments. | + +------------+------------------------------------------------------------------------------+ + | Directory | A full path to the Godot root folder | + +------------+------------------------------------------------------------------------------+ -.. image:: img/xcode_2_configure_scons.png +.. figure:: img/xcode_2_configure_scons.png + :figclass: figure-w480 + :align: center -Add a Command Line Tool target which will be used for indexing the project: +- Add a Command Line Tool target which will be used for indexing the project by + choosing **File > New > Target...**. -- In Xcode's menu, choose **File > New > Target...** and add a new Xcode - command line tool target. +.. figure:: img/xcode_3_add_new_target.png + :figclass: figure-w480 + :align: center -.. image:: img/xcode_3_add_new_target.png +- Select **OS X > Application > Command Line Tool**. -.. image:: img/xcode_4_select_command_line_target.png +.. figure:: img/xcode_4_select_command_line_target.png + :figclass: figure-w480 + :align: center -- Name it something so you know not to compile with this target (e.g. ``GodotXcodeIndex``). -- Goto the newly created target's **Build Settings** tab and look for **Header Search Paths**. -- Set **Header Search Paths** to the absolute path to Godot's source folder. -- Make it recursive by adding two asterisks (``**``) to the end of the path, - e.g. ``/Users/me/repos/godot-source/**``. +.. note:: Name it something so you know not to compile with this target (e.g. ``GodotXcodeIndex``). -Add the Godot source to the project: +- For this target open the **Build Settings** tab and look for **Header Search Paths**. +- Set **Header Search Paths** to the absolute path to the Godot root folder. You need to + include subdirectories as well. To achieve that, add two two asterisks (``**``) to the + end of the path, e.g. ``/Users/me/repos/godot-source/**``. -- Drag and drop Godot source into the project file browser. +- Add the Godot source to the project by dragging and dropping it into the project file browser. - Uncheck **Create external build system project**. -.. image:: img/xcode_5_after_add_godot_source_to_project.png +.. figure:: img/xcode_5_after_add_godot_source_to_project.png + :figclass: figure-w480 + :align: center -- Click **Next**. -- Select **Create groups**. +- Next select **Create groups** for the **Added folders** option and check *only* + your command line indexing target in the **Add to targets** section. -.. image:: img/xcode_6_after_add_godot_source_to_project_2.png +.. figure:: img/xcode_6_after_add_godot_source_to_project_2.png + :figclass: figure-w480 + :align: center -- Check *only* your command line indexing target in the - **Add to targets** section. -- Click finish. Xcode will now index the files. This may take a few minutes. +- Xcode will now index the files. This may take a few minutes. - Once Xcode is done indexing, you should have jump-to-definition, autocompletion, and full syntax highlighting. -Scheme setup ------------- +Debugging the project +--------------------- -To enable debugging support, edit the external build target's build scheme: +To enable debugging support you need to edit the external build target's build and run schemes. - Open the scheme editor of the external build target. -- Expand the **Build** menu. -- Goto **Post Actions**. -- Add a new script run action, select your project in **Provide build settings from** - as this allows you to use the``${PROJECT_DIR}`` variable. +- Locate the **Build > Post Actions** section. +- Add a new script run action +- Under **Provide build settings from** select your project. This allows to reference + the project directory within the script. +- Create a script that will give the binary a name that Xcode can recognize, e.g.: -.. image:: img/xcode_7_setup_build_post_action.png +.. code-block:: shell + + ln -f ${PROJECT_DIR}/godot/bin/godot.osx.tools.64 ${PROJECT_DIR}/godot/bin/godot + +.. figure:: img/xcode_7_setup_build_post_action.png + :figclass: figure-w480 + :align: center -- Write a script that gives the binary a name that Xcode will recognize, such as: - ``ln -f ${PROJECT_DIR}/godot/bin/godot.osx.tools.64 ${PROJECT_DIR}/godot/bin/godot`` - Build the external build target. -Edit the external build target's Run scheme: +- Open the scheme editor again and select **Run**. -- Open the scheme editor again. -- Click **Run**. - -.. image:: img/xcode_8_setup_run_scheme.png +.. figure:: img/xcode_8_setup_run_scheme.png + :figclass: figure-w480 + :align: center - Set the **Executable** to the file you linked in your post-build action script. -- Check **Debug executable** if it isn't checked already. -- You can go to **Arguments** tab and specify the full path to a - ``project.godot`` file to debug the editor instead of the project manager. - Alternatively, use ``--path`` to point to a project *folder* which will be - run directly (instead of opening the editor). +- Check **Debug executable**. +- You can add two arguments on the **Arguments** tab: + the ``-e`` flag opens the editor instead of the project manager, and the ``--path`` argument + tells the executable to open the specified project (must be provided as an *absolute* path + to the project root, not the ``project.godot`` file). -Test the Run scheme: - -- Set a breakpoint in ``platform/osx/godot_main_osx.mm``. -- If all goes well, it should break at the specified breakpoint. +To check that everything is working, put a breakpoint in ``platform/osx/godot_main_osx.mm`` and +run the project. If you run into any issues, ask for help in one of `Godot's community channels `__. diff --git a/development/cpp/custom_modules_in_cpp.rst b/development/cpp/custom_modules_in_cpp.rst index 3e748ef58..68b550f3f 100644 --- a/development/cpp/custom_modules_in_cpp.rst +++ b/development/cpp/custom_modules_in_cpp.rst @@ -257,6 +257,57 @@ The output will be ``60``. template. See the :ref:`Compiling ` pages for more information. +Compiling a module externally +----------------------------- + +Compiling a module involves moving the module's sources directly under the +engine's ``modules/`` directory. While this is the most straightforward way to +compile a module, there are a couple of reasons as to why this might not be a +practical thing to do: + +1. Having to manually copy modules sources every time you want to compile the + engine with or without the module, or taking additional steps needed to + manually disable a module during compilation with a build option similar to + ``module_summator_enabled=no``. Creating symbolic links may also be a solution, + but you may additionally need to overcome OS restrictions like needing the + symbolic link privilege if doing this via script. + +2. Depending on whether you have to work with the engine's source code, the + module files added directly to ``modules/`` changes the working tree to the + point where using a VCS (like ``git``) proves to be cumbersome as you need to + make sure that only the engine-related code is committed by filtering + changes. + +So if you feel like the independent structure of custom modules is needed, lets +take our "summator" module and move it to the engine's parent directory: + +.. code-block:: shell + + mkdir ../modules + mv modules/summator ../modules + +Compile the engine with our module by providing ``custom_modules`` build option +which accepts a comma-separated list of directory paths containing custom C++ +modules, similar to the following: + +.. code-block:: shell + + scons custom_modules=../modules + +The build system shall detect all modules under the ``../modules`` directory +and compile them accordingly, including our "summator" module. + +.. warning:: + + Any path passed to ``custom_modules`` will be converted to an absolute path + internally as a way to distinguish between custom and built-in modules. It + means that things like generating module documentation may rely on a + specific path structure on your machine. + +.. seealso:: + + :ref:`Introduction to the buildsystem - Custom modules build option `. + Improving the build system for development ------------------------------------------ @@ -307,11 +358,11 @@ library that will be dynamically loaded when starting our game's binary. Once compiled, we should end up with a ``bin`` directory containing both the ``godot*`` binary and our ``libsummator*.so``. However given the .so is not in a standard directory (like ``/usr/lib``), we have to help our binary find it -during runtime with the ``LD_LIBRARY_PATH`` environ variable: +during runtime with the ``LD_LIBRARY_PATH`` environment variable: .. code-block:: shell - export LD_LIBRARY_PATH=`pwd`/bin/ + export LD_LIBRARY_PATH="$PWD/bin/" ./bin/godot* **note**: Pay attention you have to ``export`` the environ variable otherwise @@ -386,19 +437,19 @@ There are several steps in order to setup custom docs for the module: ] The ``get_doc_path()`` function is used by the build system to determine -the location of the docs. In this case, they will be located in the +the location of the docs. In this case, they will be located in the ``modules/summator/doc_classes`` directory. If you don't define this, -the doc path for your module will fall back to the main ``doc/classes`` +the doc path for your module will fall back to the main ``doc/classes`` directory. The ``get_doc_classes()`` method is necessary for the build system to -know which registered classes belong to the module. You need to list all of your -classes here. The classes that you don't list will end up in the +know which registered classes belong to the module. You need to list all of your +classes here. The classes that you don't list will end up in the main ``doc/classes`` directory. .. tip:: - You can use git to check if you have missed some of your classes by checking the + You can use Git to check if you have missed some of your classes by checking the untracked files with ``git status``. For example:: user@host:~/godot$ git status @@ -407,13 +458,13 @@ main ``doc/classes`` directory. Untracked files: (use "git add ..." to include in what will be committed) - + doc/classes/MyClass2D.xml doc/classes/MyClass4D.xml doc/classes/MyClass5D.xml doc/classes/MyClass6D.xml ... - + 3. Now we can generate the documentation: @@ -429,13 +480,13 @@ Run command: user@host:~/godot/bin$ ./bin/ --doctool . -Now if you go to the ``godot/modules/summator/doc_classes`` folder, you will see +Now if you go to the ``godot/modules/summator/doc_classes`` folder, you will see that it contains a ``Summator.xml`` file, or any other classes, that you referenced in your ``get_doc_classes`` function. Edit the file(s) following :ref:`doc_updating_the_class_reference` and recompile the engine. -Once the compilation process is finished, the docs will become accessible within +Once the compilation process is finished, the docs will become accessible within the engine's built-in documentation system. In order to keep documentation up-to-date, all you'll have to do is simply modify @@ -443,7 +494,7 @@ one of the XML files and recompile the engine from now on. If you change your module's API, you can also re-extract the docs, they will contain the things that you previously added. Of course if you point it to your godot -folder, make sure you don't lose work by extracting older docs from an older engine build +folder, make sure you don't lose work by extracting older docs from an older engine build on top of the newer ones. Note that if you don't have write access rights to your supplied ````, diff --git a/getting_started/scripting/c_sharp/c_sharp_basics.rst b/getting_started/scripting/c_sharp/c_sharp_basics.rst index bf7010ac8..cbf910bff 100644 --- a/getting_started/scripting/c_sharp/c_sharp_basics.rst +++ b/getting_started/scripting/c_sharp/c_sharp_basics.rst @@ -50,7 +50,7 @@ Make sure you at least have the .NET Framework 4.5 targeting pack installed, you Windows (JetBrains Rider) ~~~~~~~~~~~~~~~~~~~~~~~~~ -JetBrains Rider comes with bundled MSBuild, so you just need a recent .NET Framework Developer Pack. +JetBrains Rider comes with bundled MSBuild, so nothing extra is required. Make sure to set the following preferences: - In Godot: @@ -60,7 +60,7 @@ Make sure to set the following preferences: - In Rider: - - ``TargetFrameworkVersion`` in ``csproj`` should match the installed .NET Framework Developer Pack. + - Set ``MSBuild version`` to either bundled with Rider or .NET Core. - Install **Godot support** plugin. macOS and Linux diff --git a/getting_started/scripting/gdscript/gdscript_styleguide.rst b/getting_started/scripting/gdscript/gdscript_styleguide.rst index 1ad3d5bf2..787236d5a 100644 --- a/getting_started/scripting/gdscript/gdscript_styleguide.rst +++ b/getting_started/scripting/gdscript/gdscript_styleguide.rst @@ -592,6 +592,8 @@ variables, in that order. :: + signal spawn_player(position) + enum Jobs {KNIGHT, WIZARD, ROGUE, HEALER, SHAMAN} const MAX_LIVES = 3 diff --git a/getting_started/step_by_step/exporting.rst b/getting_started/step_by_step/exporting.rst index cfc9e59e0..ae708e761 100644 --- a/getting_started/step_by_step/exporting.rst +++ b/getting_started/step_by_step/exporting.rst @@ -111,7 +111,7 @@ changed: position.y = clamp(position.y, 0, screen_size.y) if velocity.x != 0: - $AnimatedSprite.animation = "right" + $AnimatedSprite.animation = "walk" $AnimatedSprite.flip_v = false $AnimatedSprite.flip_h = velocity.x < 0 elif velocity.y != 0: @@ -218,7 +218,7 @@ changed: if (velocity.x != 0) { - animatedSprite.Animation = "right"; + animatedSprite.Animation = "walk"; animatedSprite.FlipV = false; animatedSprite.FlipH = velocity.x < 0; } @@ -319,7 +319,7 @@ Before you can export your project for Android, you must download the following software: * Android SDK: https://developer.android.com/studio/ -* Java JDK: http://www.oracle.com/technetwork/java/javase/downloads/index.html +* Open JDK(version 8 is required, more recent versions won't work): https://adoptopenjdk.net/index.html When you run Android Studio for the first time, click on *Configure -> SDK Manager* and install "Android SDK Platform Tools". This installs the `adb` command-line diff --git a/getting_started/step_by_step/your_first_game.rst b/getting_started/step_by_step/your_first_game.rst index dbe4e1099..b60639b46 100644 --- a/getting_started/step_by_step/your_first_game.rst +++ b/getting_started/step_by_step/your_first_game.rst @@ -375,7 +375,7 @@ function: .. code-tab:: gdscript GDScript if velocity.x != 0: - $AnimatedSprite.animation = "right" + $AnimatedSprite.animation = "walk" $AnimatedSprite.flip_v = false # See the note below about boolean assignment $AnimatedSprite.flip_h = velocity.x < 0 @@ -387,7 +387,7 @@ function: if (velocity.x != 0) { - animatedSprite.Animation = "right"; + animatedSprite.Animation = "walk"; animatedSprite.FlipV = false; // See the note below about boolean assignment animatedSprite.FlipH = velocity.x < 0; @@ -634,7 +634,7 @@ choose one of the three animation types: First, we get the list of animation names from the AnimatedSprite's ``frames`` property. This returns an Array containing all three animation names: -``["walk", "swim", "fly]``. +``["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 @@ -1133,7 +1133,7 @@ functions: emit_signal("start_game") func _on_MessageTimer_timeout(): - $MessageLabel.hide() + $Message.hide() .. code-tab:: csharp @@ -1145,7 +1145,7 @@ functions: public void OnMessageTimerTimeout() { - GetNode