From 8e5258c966f4100752a93b3fd761fc5ff2c29b34 Mon Sep 17 00:00:00 2001 From: Relintai Date: Thu, 12 Jan 2023 22:00:14 +0100 Subject: [PATCH] More code block cleanups. --- .../contributing/bisecting_regressions.md | 20 +-- community/contributing/building_the_manual.md | 17 +-- .../class_reference_writing_guidelines.md | 45 +++--- .../contributing/code_style_guidelines.md | 37 +++-- .../contributing_to_the_documentation.md | 15 +- .../contributing/cpp_usage_guidelines.md | 4 +- .../contributing/docs_writing_guidelines.md | 139 +++++++++--------- .../contributing/documentation_guidelines.md | 6 +- .../editor_and_docs_localization.md | 14 +- community/contributing/pr_workflow.md | 84 +++++------ .../updating_the_class_reference.md | 4 +- .../compiling/compiling_for_android.md | 32 ++-- development/compiling/compiling_for_ios.md | 20 +-- development/compiling/compiling_for_osx.md | 72 ++++++--- development/compiling/compiling_for_uwp.md | 12 +- development/compiling/compiling_for_web.md | 32 +++- .../compiling/compiling_for_windows.md | 64 +++++--- development/compiling/compiling_for_x11.md | 66 +++++---- .../compiling_with_script_encryption_key.md | 12 +- .../cross-compiling_for_ios_on_linux.md | 41 +++--- development/compiling/getting_source.md | 8 +- .../introduction_to_the_buildsystem.md | 57 +++---- development/compiling/optimizing_for_size.md | 32 ++-- .../cpp/binding_to_external_libraries.md | 56 +++---- .../cpp/common_engine_methods_and_macros.md | 41 +++--- .../cpp/configuring_an_ide/kdevelop.md | 4 +- development/cpp/configuring_an_ide/xcode.md | 4 +- development/cpp/core_types.md | 24 +-- development/cpp/custom_audiostreams.md | 23 ++- development/cpp/custom_godot_servers.md | 44 +++--- development/cpp/custom_modules_in_cpp.md | 95 ++++++------ .../cpp/custom_resource_format_loaders.md | 43 +++--- .../cpp/introduction_to_godot_development.md | 8 +- development/cpp/macos_debug.md | 8 +- development/cpp/object_class.md | 80 +++++----- development/editor/creating_icons.md | 8 +- development/file_formats/tscn.md | 59 +++----- tutorials/2d/particle_systems_2d.md | 4 +- .../portals/advanced_room_and_portal_usage.md | 4 +- tutorials/animation/playing_videos.md | 8 +- tutorials/assets_pipeline/importing_scenes.md | 16 +- .../assets_pipeline/importing_translations.md | 4 +- .../best_practices/project_organization.md | 12 +- .../best_practices/version_control_systems.md | 4 +- tutorials/editor/command_line_tutorial.md | 65 ++++---- tutorials/editor/default_key_mapping.md | 3 - .../changing_application_icon_for_windows.md | 8 +- tutorials/export/exporting_basics.md | 8 +- tutorials/export/exporting_for_android.md | 12 +- .../export/exporting_for_dedicated_servers.md | 12 +- tutorials/export/exporting_for_uwp.md | 12 +- tutorials/export/exporting_for_web.md | 16 +- tutorials/export/exporting_projects.md | 20 +-- tutorials/export/feature_tags.md | 5 +- tutorials/i18n/internationalizing_games.md | 16 +- tutorials/i18n/localization_using_gettext.md | 36 ++--- tutorials/inputs/input_examples.md | 4 +- .../your_second_3d_shader.md | 80 +++++----- tutorials/ui/bbcode_in_richtextlabel.md | 20 +-- tutorials/ui/size_and_anchors.md | 4 +- 60 files changed, 906 insertions(+), 797 deletions(-) diff --git a/community/contributing/bisecting_regressions.md b/community/contributing/bisecting_regressions.md index 4e77e84..b99c60a 100644 --- a/community/contributing/bisecting_regressions.md +++ b/community/contributing/bisecting_regressions.md @@ -81,11 +81,11 @@ The commit hash is written inside that file. If you're using a stable release as the "good" or "bad" build, use one of the following commit hashes depending on the version: -.. code-block:: none - +``` 3.2-stable 3.1-stable 3.0-stable +``` To refer to the latest state of the master branch, you can use `master` instead of a commit hash. @@ -94,21 +94,21 @@ instead of a commit hash. is done, in the terminal window, use `cd` to reach the Godot repository folder and enter the following command: -.. code-block:: shell - +``` # is hash of the build that works as expected. # is hash of the build exhibiting the bug. $ git bisect start $ git bisect good $ git bisect bad +``` Compile Godot. This assumes you've set up a build environment: -.. code-block:: shell - +``` # is the platform you're targeting for regression testing, # like "windows", "x11" or "osx". $ scons platform= -j4 +``` Since building Godot takes a while, you want to dedicate as many CPU threads as possible to the task. This is what the `-j` parameter does. Here, the command @@ -118,15 +118,15 @@ Run the binary located in the `bin/` folder and try to reproduce the bug. If the build **still** exhibits the bug, run the following command: -.. code-block:: shell - +``` $ git bisect bad +``` If the build **does not** exhibit the bug, run the following command: -.. code-block:: shell - +``` $ git bisect good +``` After entering one of the commands above, Git will switch to a different commit. You should now build Godot again, try to reproduce the bug, then enter `git diff --git a/community/contributing/building_the_manual.md b/community/contributing/building_the_manual.md index 6a51713..8d5e3d5 100644 --- a/community/contributing/building_the_manual.md +++ b/community/contributing/building_the_manual.md @@ -25,40 +25,39 @@ Note: You may need to write `python3 -m pip` (Unix) or `py -m pip` (Windows) instead of `pip3`. If both approaches fail, `check that you have pip3 installed ( https://pip.pypa.io/en/stable/installation/ )`. -.. code:: sh - +``` git clone https://github.com/godotengine/godot-docs.git pip3 install -r requirements.txt - +``` With the programs installed, you can build the HTML documentation from the root folder of this repository with the following command: -.. code:: sh - +``` # On Linux and macOS make html # On Windows, you need to execute the `make.bat` file instead. make.bat html +``` If you run into errors, you may try the following command: -.. code:: sh - +``` make SPHINXBUILD=~/.local/bin/sphinx-build html +``` Building the documentation requires at least 8 GB of RAM to run without disk swapping, which slows it down. If you have at least 16 GB of RAM, you can speed up compilation by running: -.. code:: sh - +``` # On Linux/macOS make html SPHINXOPTS=-j2 # On Windows set SPHINXOPTS=-j2 && make html +``` The compilation will take some time as the `classes/` folder contains hundreds of files. diff --git a/community/contributing/class_reference_writing_guidelines.md b/community/contributing/class_reference_writing_guidelines.md index 864463b..8524800 100644 --- a/community/contributing/class_reference_writing_guidelines.md +++ b/community/contributing/class_reference_writing_guidelines.md @@ -15,8 +15,7 @@ See also: 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. @@ -61,7 +60,7 @@ The reference for each class is contained in an XML file like the one below: - +``` 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 @@ -71,14 +70,14 @@ 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 `writing guidelines ( doc_docs_writing_guidelines )` to keep your descriptions short and easy to read. @@ -110,7 +109,7 @@ 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 `compilation -guide +``` - `-i` means that the changes should be written directly to the file (by default clang-format would only output the fixed version to the terminal). @@ -159,8 +159,7 @@ ones, the following rules should be followed: Example: -.. code-block:: cpp - +``` /*************************************************************************/ /* my_new_file.h */ /*************************************************************************/ @@ -203,9 +202,9 @@ Example: ... #endif // MY_NEW_FILE_H +``` -.. code-block:: cpp - +``` /*************************************************************************/ /* my_new_file.cpp */ /*************************************************************************/ @@ -243,6 +242,7 @@ Example: #include #include +``` Java ---- @@ -272,10 +272,9 @@ Installation Here's how to install black: -:: - +``` pip3 install black --user - +``` You then have different possibilities to apply black to your changes: @@ -285,9 +284,9 @@ Manual usage You can apply `black` manually to one or more files with the following command: -:: - +``` black -l 120 +``` - `-l 120` means that the allowed number of characters per line is 120. This number was agreed upon by the developers. @@ -328,20 +327,20 @@ Godot's codebase. **Example:** -.. code-block:: cpp - +``` // Compute the first 10,000 decimals of Pi. // FIXME: Don't crash when computing the 1,337th decimal due to `increment` // being negative. +``` Don't repeat what the code says in a comment. Explain the *why* rather than *how*. **Bad:** -.. code-block:: cpp - +``` // Draw loading screen. draw_load_screen(); +``` You can use Javadoc-style comments above function or macro definitions. It's recommended to use Javadoc-style comments *only* for methods which are not @@ -351,8 +350,7 @@ instead. **Example:** -.. code-block:: cpp - +``` /** * Returns the number of nodes in the universe. * This can potentially be a very large number, hence the 64-bit return type. @@ -360,14 +358,15 @@ instead. uint64_t Universe::get_node_count() { // ... } +``` For member variables, don't use Javadoc-style comments but use single-line comments instead: -.. code-block:: cpp - +``` class Universe { // The cached number of nodes in the universe. // This value may not always be up-to-date with the current number of nodes // in the universe. uint64_t node_count_cached = 0; }; +``` diff --git a/community/contributing/contributing_to_the_documentation.md b/community/contributing/contributing_to_the_documentation.md index 706ee43..3d60434 100644 --- a/community/contributing/contributing_to_the_documentation.md +++ b/community/contributing/contributing_to_the_documentation.md @@ -125,12 +125,10 @@ Titles Always begin pages with their title and a Sphinx reference name: -:: - - - +``` Insert your title here ====================== +``` The reference `doc_insert_your_title_here` and the title should match. @@ -169,18 +167,17 @@ 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 - +``` ![](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 ( files/myfilename.zip )` - +``` License ------- diff --git a/community/contributing/cpp_usage_guidelines.md b/community/contributing/cpp_usage_guidelines.md index 7ca9843..06683d6 100644 --- a/community/contributing/cpp_usage_guidelines.md +++ b/community/contributing/cpp_usage_guidelines.md @@ -75,13 +75,13 @@ Note: 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 diff --git a/community/contributing/docs_writing_guidelines.md b/community/contributing/docs_writing_guidelines.md index 05a5c11..dba06e5 100644 --- a/community/contributing/docs_writing_guidelines.md +++ b/community/contributing/docs_writing_guidelines.md @@ -49,33 +49,31 @@ Use the active voice when possible. Take the classes, methods, and constants you describe as the subject. It's natural to write using the passive voice, but it's harder to read and produces longer sentences. -.. highlight:: none - Passive: -:: - +``` The man **was bitten** by the dog. +``` Active: -:: - +``` The dog bit the man. +``` **Don't** use the passive voice: -:: - +``` void edit_set_pivot ( Vector2 pivot ) [...] This method **is implemented** only in some nodes that inherit Node2D. +``` **Do** use the node's name as a noun: -:: - +``` void edit_set_pivot ( Vector2 pivot ) [...] Only some Node2Ds **implement** this method. +``` Use precise action verbs ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -86,18 +84,18 @@ and any expression you can replace with a single word. **Don't** repeat the method's name. It already states it sets the pivot value to a new one: -:: - +``` void edit_set_pivot ( Vector2 pivot ) Set the pivot position of the 2D node to [code]pivot[/code] value. [...] +``` **Do** explain what's the consequence of this "set": use precise verbs like `place`, `position`, `rotate`, `fade`, etc. -:: - +``` void edit_set_pivot ( Vector2 pivot ) Position the node's pivot to the [code]pivot[/code] value. [...] +``` Avoid verbs that end in -ing ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -107,17 +105,17 @@ The progressive forms describe continuous actions. E.g. "is calling", **Don't** use the progressive form for instant changes. -:: - +``` Vector2 move ( Vector2 rel_vec ) Move the body in the given direction, **stopping** if there is an obstacle. [...] +``` **Do** use simple present, past, or future. -:: - +``` Vector2 move ( Vector2 rel_vec ) Moves the body in the vector's direction. The body **stops** if it collides with an obstacle. [...] +``` Exception: If the subject is not clear, replacing "ing" verbs is not an improvement. For example, in the previous sentence, "it replaces" @@ -128,7 +126,6 @@ continuous in time. Anything like animation or coroutines. Tip: - Verbs can turn into adjectival nouns with -ing. This is not a conjugation, so you may use them: `the remaining movement`, `the missing file`, etc. @@ -142,15 +139,15 @@ add key information to the description. **Don't** use redundant or meaningless adverbs. Words that lengthen the documentation but don't add any information: -:: - +``` **Basically** a big texture [...] +``` **Do** write short sentences in a simple, descriptive language: -:: - +``` A big texture [...] +``` Ban these 8 words ~~~~~~~~~~~~~~~~~ @@ -175,48 +172,48 @@ easily, actually, clearly. **Don't** example. The banned words lengthen the description and take attention away from the most important info: -:: - +``` **TextureRect** Control frame that **simply** draws an assigned texture. It can stretch or not. It's a **simple** way to **just** show an image in a UI. +``` **Do** remove them: -:: - +``` **TextureRect** [Control] node that displays a texture. The texture can stretch to the node's bounding box or stay in the center. Useful to display sprites in your UIs. +``` "Simple" never helps. Remember, for other users, anything could be complex or frustrate them. There's nothing like a good old *it's simple* to make you cringe. Here's the old brief description, the first sentence on the Timer node's page: -:: - +``` **Timer** A **simple** Timer node. +``` **Do** explain what the node does instead: -:: - +``` **Timer** Calls a function of your choice after a certain duration. +``` **Don't** use "basic", it is too vague: -:: - +``` **Vector3** Vector class, which performs **basic** 3D vector math operations. +``` **Do** use the brief description to offer an overview of the node: -:: - +``` **Vector3** Provides essential math functions to manipulate 3D vectors: cross product, normalize, rotate, etc. +``` Use explicit references ~~~~~~~~~~~~~~~~~~~~~~~ @@ -226,15 +223,15 @@ Favor explicit references over implicit ones. **Don't** use words like "the former", "the latter", etc. They're not the most common in English, and they require you to check the reference. -:: - +``` [code]w[/code] and [code]h[/code] define right and bottom margins. The **latter** two resize the texture so it fits in the defined margin. +``` **Do** repeat words. They remove all ambiguity: -:: - +``` [code]w[/code] and [code]h[/code] define right and bottom margins. **[code]w[/code] and [code]h[/code]** resize the texture so it fits the margin. +``` If you need to repeat the same variable name 3 or 4 times, you probably need to rephrase your description. @@ -247,16 +244,16 @@ milk" instead. **Don't** write "of the X": -:: - +``` The region **of the AtlasTexture that is** used. +``` **Do** use `'s`. It lets you put the main subject at the start of the sentence, and keep it short: -:: - +``` The **AtlasTexture's** used region. +``` Use the Oxford comma to enumerate anything ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -271,17 +268,16 @@ From the Oxford dictionary: **Don't** leave the last element of a list without a comma: -:: - +``` Create a KinematicBody2D node, a CollisionShape2D node and a sprite node. +``` **Do** add a comma before `and` or `or`, for the last element of a list with more than two elements. -:: - +``` Create a KinematicBody2D node, a CollisionShape2D node, and a sprite node. - +``` How to write methods and classes -------------------------------- @@ -298,45 +294,43 @@ The exception is topics that explain static typing concepts to users. **Don't** add a type hint with a colon or by casting: -:: - +``` const MainAttack := preload("res://fire_attack.gd") var hit_points := 5 var name: String = "Bob" var body_sprite := $Sprite as Sprite - +``` **Do** write constants and variables with dynamic typing: -:: - +``` const MainAttack = preload("res://fire_attack.gd") var hit_points = 5 var name = "Bob" var body_sprite = $Sprite - +``` **Don't** write functions with inferred arguments or return types: -:: - +``` func choose(arguments: PackedStringArray) -> String: # Chooses one of the arguments from array with equal chances randomize() var size := arguments.size() var choice: int = randi() % size return arguments[choice] +``` **Do** write functions using dynamic typing: -:: - +``` func choose(arguments): # Chooses one of the arguments from array with equal chances randomize() var size = arguments.size() var choice = randi() % size return arguments[choice] +``` Use real-world code examples where appropriate ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -351,19 +345,18 @@ could use the code snippets in a live project. **Don't** write made-up examples: -:: - +``` onready var a = preload("res://MyPath") onready var my_node = $MyNode func foo(): # Do stuff +``` **Do** write concrete examples: -:: - +``` onready var sfx_player_gun = preload("res://Assets/Sound/SFXPlayerGun.ogg") onready var audio_player = $Audio/AudioStreamPlayer @@ -371,6 +364,7 @@ could use the code snippets in a live project. func play_shooting_sound(): audio_player.stream = sfx_player_gun audio_player.play() +``` Of course, there are times when using real-world examples is impractical. In those situations, you should still avoid using names such as `my_var`, @@ -390,17 +384,17 @@ functionality, in up to 200 characters. **Don't** write tiny and vague summaries: -:: - +``` **Node2D** Base node for 2D system. +``` **Do** give an overview of the node's functionality: -:: - +``` **Node2D** A 2D game object, inherited by all 2D-related nodes. Has a position, rotation, scale, and Z index. +``` Use the node's full description to provide more information, and a code example, if possible. @@ -414,17 +408,17 @@ for any method whose name starts with `set` or `get`. **Don't** use the passive voice: -:: - +``` Vector2 move ( Vector2 rel_vec ) [...] The returned vector is how much movement was remaining before being stopped. +``` **Do** always use "Returns". -:: - +``` Vector2 move ( Vector2 rel_vec ) [...] Returns the remaining movement before the body was stopped. +``` Notice the exception to the "direct voice" rule: with the move method, an external collider can influence the method and the body that calls @@ -441,11 +435,10 @@ Also, surround boolean values, variable names and methods with `[code][/code]`. **Do** start with "if true": -:: - +``` Timer.autostart If [code]true[/code], the timer will automatically start when entering the scene tree. - +``` Use `[code]` around arguments ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/community/contributing/documentation_guidelines.md b/community/contributing/documentation_guidelines.md index 0c34dae..6459e06 100644 --- a/community/contributing/documentation_guidelines.md +++ b/community/contributing/documentation_guidelines.md @@ -94,12 +94,10 @@ Titles Always begin pages with their title and a Sphinx reference name: -:: - - - +``` Insert your title here ====================== +``` The reference allows linking to this page using the ``` format, e.g. ```doc_insert_your_title_here``` would link to the above example page diff --git a/community/contributing/editor_and_docs_localization.md b/community/contributing/editor_and_docs_localization.md index 98e7f76..2e1b94f 100644 --- a/community/contributing/editor_and_docs_localization.md +++ b/community/contributing/editor_and_docs_localization.md @@ -3,8 +3,6 @@ Editor and docs localization ============================ -.. highlight:: none - Godot aims to make game development available to everyone, including people who may not know or be comfortable with English. Therefore, we do our best to make the most important resources available in many languages, thanks to the @@ -222,7 +220,7 @@ The editor translations originate from C++ strings, and may use: placed in your translation where necessary for it to be meaningful after substitution. You may need to refer to the source string location to understand what kind of content will be substituted if it's not clear from the - sentence. Example (`%s` will be substituted with a file name or path):: + sentence. Example (`%s` will be substituted with a file name or path): # PO file: "There is no '%s' file." @@ -236,7 +234,7 @@ The editor translations originate from C++ strings, and may use: breaks in the same way as the original English string (Weblate will issue a warning if you don't). Line breaks might sometimes be used for vertical spacing, or manual wrapping of long lines which would otherwise be too long - especially in the editor translation). Example:: + especially in the editor translation). Example: # PO file: "Scene '%s' is currently being edited.\n" @@ -256,8 +254,9 @@ Online documentation (RST) The documentation translations originate from reStructuredText (RST) files, which also use their own markup syntax to style text, create internal and -external links, etc. Here are some examples:: +external links, etc. Here are some examples: +``` # "development" is styled bold. # "Have a look here" is a link pointing to https://docs.godotengine.org/en/latest. # You should translate "Have a look here", but not the URL, unless there is @@ -293,6 +292,7 @@ external links, etc. Here are some examples:: Save the scene. Click Scene -> Save, or press :kbd:`Ctrl + S` on Windows/Linux or :kbd:`Cmd + S` on macOS. +``` See also: @@ -312,13 +312,15 @@ Some of the tags used are from the original BBCode (e.g. `[b]Bold[/b]` and `[i]Italics[/i]`), while others are Godot-specific and used for advanced features such as inline code (e.g. `[code]true[/code]`), linking to another class (e.g. `[Node2D]`) or to a property in a given class (e.g. -`[member Node2D.position]`), or for multiline code blocks. Example:: +`[member Node2D.position]`), or for multiline code blocks. Example: +``` Returns a color according to the standardized [code]name[/code] with [code]alpha[/code] ranging from 0 to 1. [codeblock] red = ColorN("red", 1) [/codeblock] Supported color names are the same as the constants defined in [Color]. +``` In the above example, `[code]name[/code]`, `[code]alpha[/code]`, and `[Color]` should *not* be translated, as they refer respectively to argument diff --git a/community/contributing/pr_workflow.md b/community/contributing/pr_workflow.md index 30dea26..905214d 100644 --- a/community/contributing/pr_workflow.md +++ b/community/contributing/pr_workflow.md @@ -95,9 +95,9 @@ Note: To clone your fork from GitHub, use the following command: -:: - +``` $ git clone https://github.com/USERNAME/godot +``` Note: In our examples, the "$" character denotes the command line prompt @@ -107,16 +107,16 @@ Note: After a little while, you should have a `godot` directory in your current working directory. Move into it using the `cd` command: -:: - +``` $ cd godot +``` We will start by setting up a reference to the original repository that we forked: -:: - +``` $ git remote add upstream https://github.com/godotengine/godot $ git fetch upstream +``` This will create a reference named `upstream` pointing to the original `godotengine/godot` repository. This will be useful when you want to pull new @@ -150,44 +150,44 @@ By default, the `git clone` should have put you on the `master` branch of your fork (`origin`). To start your own feature development, we will create a feature branch: -:: - +``` # Create the branch based on the current branch (master) $ git branch better-project-manager # Change the current branch to the new one $ git checkout better-project-manager +``` This command is equivalent: -:: - +``` # Change the current branch to a new named one, based on the current branch $ git checkout -b better-project-manager +``` If you want to go back to the `master` branch, you'd use: -:: - +``` $ git checkout master +``` You can see which branch you are currently on with the `git branch` command: -:: - +``` $ git branch 2.1 * better-project-manager master +``` Be sure to always go back to the `master` branch before creating a new branch, as your current branch will be used as the base for the new one. Alternatively, you can specify a custom base branch after the new branch's name: -:: - +``` $ git checkout -b my-new-feature master +``` Updating your branch -------------------- @@ -202,9 +202,9 @@ To ensure there won't be conflicts between the feature you develop and the current upstream `master` branch, you will have to update your branch by *pulling* the upstream branch. -:: - +``` $ git pull --rebase upstream master +``` The `--rebase` argument will ensure that any local changes that you committed will be re-applied *on top* of the pulled branch, which is usually what we want @@ -299,8 +299,7 @@ need to make changes, and learn by doing. Here's how the shell history could look like on our example: -:: - +``` # It's nice to know where you're starting from $ git log @@ -328,6 +327,7 @@ Here's how the shell history could look like on our example: $ git add editor/project_manager.cpp $ git commit -m "Add a pretty banner to the project manager" $ git log +``` With this, we should have two new commits in our `better-project-manager` branch which were not in the `master` branch. They are still only local @@ -341,17 +341,17 @@ done in the local repository (unlike Subversion where a commit will modify the remote repository directly). You need to *push* the new commits to a remote branch to share them with the world. The syntax for this is: -:: - +``` $ git push ( remote> ( local branch>[:( remote branch>] +``` The part about the remote branch can be omitted if you want it to have the same name as the local branch, which is our case in this example, so we will do: -:: - +``` $ git push origin better-project-manager +``` Git will ask you for your username and password, and the changes will be sent to your remote. If you check the fork's page on GitHub, you should see a new @@ -390,8 +390,7 @@ The good news is that you can modify a pull request simply by acting on the branch you made the pull request from. You can e.g. make a new commit on that branch, push it to your fork, and the PR will be updated automatically: -:: - +``` # Check out your branch again if you had changed in the meantime $ git checkout better-project-manager @@ -400,6 +399,7 @@ branch, push it to your fork, and the PR will be updated automatically: $ git add editor/project_manager.cpp $ git commit -m "Fix a typo in the banner's title" $ git push origin better-project-manager +``` However, be aware that in our PR workflow, we favor commits that bring the codebase from one functional state to another functional state, without having @@ -409,8 +409,7 @@ reason to keep the changes separate). Instead of authoring a new commit, consider using `git commit --amend` to amend the previous commit with your fixes. The above example would then become: -:: - +``` # Check out your branch again if you had changed in the meantime $ git checkout better-project-manager @@ -423,6 +422,7 @@ fixes. The above example would then become: # As we modified the last commit, it no longer matches the one from your # remote branch, so we need to force push to overwrite that branch. $ git push --force origin better-project-manager +``` .. Kept for compatibility with the previous title, linked in many PRs. @@ -457,9 +457,9 @@ While you can give any commit ID to `git rebase -i` and review everything in between, the most common and convenient workflow involves rebasing on the upstream `master` branch, which you can do with: -:: - +``` $ git rebase -i upstream/master +``` Note: Referencing branches in Git is a bit tricky due to the distinction @@ -481,10 +481,10 @@ This will open a text editor (`vi` by default, see `Git docs ( https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration#_core_editor )` to configure your favorite one) with something which may look like this: -.. code-block:: text - +``` pick 1b4aad7 Add a pretty banner to the project manager pick e07077e Fix a typo in the banner's title +``` The editor will also show instructions regarding how you can act on those commits. In particular, it should tell you that "pick" means to use that @@ -494,10 +494,10 @@ that "fixup" will discard the commit log from the squashed commit. In our example, we are not interested in keeping the log of the "Fix a typo" commit, so we use: -.. code-block:: text - +``` pick 1b4aad7 Add a pretty banner to the project manager fixup e07077e Fix a typo in the banner's title +``` Upon saving and quitting the editor, the rebase will occur. The second commit will be melded into the first one, and `git log` and `git show` should @@ -509,22 +509,22 @@ diverged. Indeed, commit 1b4aad7 in the above example will have changed, and therefore got a new commit hash. If you try to push to your remote branch, it will raise an error: -:: - +``` $ git push origin better-project-manager To https://github.com/akien-mga/godot ! [rejected] better-project-manager -> better-project-manager (non-fast-forward) error: failed to push some refs to 'https://akien-mga@github.com/akien-mga/godot' hint: Updates were rejected because the tip of your current branch is behind hint: its remote counterpart. +``` This is a sane behavior, Git will not let you push changes that would override remote content. But that's actually what we want to do here, so we will have to *force* it: -:: - +``` $ git push --force origin better-project-manager +``` And tadaa! Git will happily *replace* your remote branch with what you had locally (so make sure that's what you wanted, using `git log`). This will @@ -540,18 +540,18 @@ for the remote branch on GitHub. To delete our better project manager branch locally, use this command: -:: - +``` $ git branch -d better-project-manager +``` Alternatively, if the branch hadn't been merged yet and we wanted to delete it anyway, instead of `-d` you would use `-D`. Next, to delete the remote branch on GitHub use this command: -:: - +``` $ git push origin -d better-project-manager +``` You can also delete the remote branch from the GitHub PR itself, a button should appear once it has been merged or closed. diff --git a/community/contributing/updating_the_class_reference.md b/community/contributing/updating_the_class_reference.md index e3cbca2..e2bef6b 100644 --- a/community/contributing/updating_the_class_reference.md +++ b/community/contributing/updating_the_class_reference.md @@ -70,9 +70,11 @@ When you create a new class or modify the engine's API, you need to re-generate To do so, you first need to compile Godot. See the `doc_introduction_to_the_buildsystem` page to learn how. Then, execute the compiled Godot binary from the Godot root directory with the `--doctool` option. -For example, if you're on 64-bit Linux, the command is:: +For example, if you're on 64-bit Linux, the command is: +``` ./bin/godot.linuxbsd.tools.64 --doctool +``` The XML files in doc/classes should then be up-to-date with current Godot Engine features. You can then check what changed using the `git diff` command. Please diff --git a/development/compiling/compiling_for_android.md b/development/compiling/compiling_for_android.md index 6250e2e..163f8f4 100644 --- a/development/compiling/compiling_for_android.md +++ b/development/compiling/compiling_for_android.md @@ -61,15 +61,15 @@ Setting up the buildsystem - Accept the SDK component licenses by running the following command where `android_sdk_path` is the path to the Android SDK, then answering all the prompts with `y`: - :: - +``` tools/bin/sdkmanager --sdk_root=( android_sdk_path> --licenses +``` - Complete setup by running the following command where `android_sdk_path` is the path to the Android SDK. - :: - +``` tools/bin/sdkmanager --sdk_root=( android_sdk_path> "platform-tools" "build-tools;30.0.3" "platforms;android-29" "cmdline-tools;latest" "cmake;3.10.2.4988404" +``` See also: To set the environment variable on Windows, press :kbd:`Windows + R`, type @@ -95,8 +95,7 @@ root directory with the following arguments: - Release template (used when exporting with **Debugging Enabled** unchecked) -:: - +``` scons platform=android target=release android_arch=armv7 scons platform=android target=release android_arch=arm64v8 cd platform/android/java @@ -104,14 +103,13 @@ root directory with the following arguments: .\gradlew generateGodotTemplates # On Linux and macOS ./gradlew generateGodotTemplates - +``` The resulting APK will be located at `bin/android_release.apk`. - Debug template (used when exporting with **Debugging Enabled** checked) -:: - +``` scons platform=android target=release_debug android_arch=armv7 scons platform=android target=release_debug android_arch=arm64v8 cd platform/android/java @@ -119,7 +117,7 @@ The resulting APK will be located at `bin/android_release.apk`. .\gradlew generateGodotTemplates # On Linux and macOS ./gradlew generateGodotTemplates - +``` The resulting APK will be located at `bin/android_debug.apk`. @@ -131,8 +129,7 @@ command a third and fourth time with the `android_arch=x86`, and `android_arch=x86_64` arguments before building the APK with Gradle. For example, for the release template: -:: - +``` scons platform=android target=release android_arch=armv7 scons platform=android target=release android_arch=arm64v8 scons platform=android target=release android_arch=x86 @@ -142,7 +139,7 @@ example, for the release template: .\gradlew generateGodotTemplates # On Linux and macOS ./gradlew generateGodotTemplates - +``` This will create a fat binary that works on all platforms. The final APK size of exported projects will depend on the platforms you choose @@ -154,14 +151,13 @@ Cleaning the generated export templates You can use the following commands to remove the generated export templates: -:: - +``` cd platform/android/java # On Windows .\gradlew cleanGodotTemplates # On Linux and macOS ./gradlew cleanGodotTemplates - +``` Using the export templates -------------------------- @@ -226,9 +222,9 @@ If so: If it still fails, open a command line and run `logcat ( https://developer.android.com/studio/command-line/logcat )`: -:: - +``` adb logcat +``` Then check the output while the application is installed; the error message should be presented there. diff --git a/development/compiling/compiling_for_ios.md b/development/compiling/compiling_for_ios.md index 8a5a531..2cc5396 100644 --- a/development/compiling/compiling_for_ios.md +++ b/development/compiling/compiling_for_ios.md @@ -30,24 +30,24 @@ Compiling Open a Terminal, go to the root dir of the engine source code and type: -:: - +``` $ scons p=iphone target=debug +``` for a debug build, or: -:: - +``` $ scons p=iphone target=release +``` for a release build (check `platform/iphone/detect.py` for the compiler flags used for each configuration). Alternatively, you can run -:: - +``` $ scons p=iphone arch=x86_64 target=debug +``` for a Simulator executable. @@ -57,24 +57,24 @@ The best way to provide these is to create a bundle in which there are both 32-b It can be done in three steps: first compile the 32-bit version, then compile the 64-bit version and then use `lipo` to bundle them into one "universal" binary. All those steps can be performed with following commands: -:: - +``` $ scons p=iphone tools=no target=release arch=arm $ scons p=iphone tools=no target=release arch=arm64 $ lipo -create bin/libgodot.iphone.opt.arm.a bin/libgodot.iphone.opt.arm64.a -output bin/libgodot.iphone.release.fat.a $ lipo -create bin/libgodot_camera_module.iphone.opt.arm.a bin/libgodot_camera_module.iphone.opt.arm64.a -output bin/libgodot_camera_module.iphone.release.fat.a $ lipo -create bin/libgodot_arkit_module.iphone.opt.arm.a bin/libgodot_arkit_module.iphone.opt.arm64.a -output bin/libgodot_arkit_module.iphone.release.fat.a +``` If you also want to provide a simulator build (reduces the chance of any linker errors with dependencies), you'll need to build and lipo the `x86_64` architecture as well. -:: - +``` $ scons p=iphone tools=no target=release arch=arm $ scons p=iphone tools=no target=release arch=arm64 $ scons p=iphone tools=no target=release arch=x86_64 $ lipo -create bin/libgodot.iphone.opt.arm.a bin/libgodot.iphone.opt.arm64.a bin/libgodot.iphone.opt.x86_64.a -output bin/libgodot.iphone.release.fat.a $ lipo -create bin/libgodot_camera_module.iphone.opt.arm.a bin/libgodot_camera_module.iphone.opt.arm64.a bin/libgodot_camera_module.iphone.opt.x86_64.a -output bin/libgodot_camera_module.iphone.release.fat.a $ lipo -create bin/libgodot_arkit_module.iphone.opt.arm.a bin/libgodot_arkit_module.iphone.opt.arm64.a bin/libgodot_arkit_module.iphone.opt.x86_64.a -output bin/libgodot_arkit_module.iphone.release.fat.a +``` Run --- diff --git a/development/compiling/compiling_for_osx.md b/development/compiling/compiling_for_osx.md index fc5bd48..8a5f077 100644 --- a/development/compiling/compiling_for_osx.md +++ b/development/compiling/compiling_for_osx.md @@ -23,18 +23,22 @@ For compiling under macOS, the following is required: Note: If you have `Homebrew ( https://brew.sh/ )` installed, you can easily - install SCons and yasm using the following command:: + install SCons and yasm using the following command: +``` brew install scons yasm +``` Installing Homebrew will also fetch the Command Line Tools for Xcode automatically if you don't have them already. Similarly, if you have `MacPorts ( https://www.macports.org/ )` installed, you can easily install SCons and yasm using the - following command:: + following command: +``` sudo port install scons yasm +``` See also: To get the Godot source code for compiling, see @@ -48,17 +52,23 @@ Compiling Start a terminal, go to the root directory of the engine source code. -To compile for Intel (x86-64) powered Macs, use:: +To compile for Intel (x86-64) powered Macs, use +``` scons platform=osx arch=x86_64 --jobs=$(sysctl -n hw.logicalcpu) +``` -To compile for Apple Silicon (ARM64) powered Macs, use:: +To compile for Apple Silicon (ARM64) powered Macs, use: +``` scons platform=osx arch=arm64 --jobs=$(sysctl -n hw.logicalcpu) +``` -To support both architectures in a single "Universal 2" binary, run the above two commands and then use `lipo` to bundle them together:: +To support both architectures in a single "Universal 2" binary, run the above two commands and then use `lipo` to bundle them together: +``` lipo -create bin/godot.osx.tools.x86_64 bin/godot.osx.tools.arm64 -output bin/godot.osx.tools.universal +``` If all goes well, the resulting binary executable will be placed in the `bin/` subdirectory. This executable file contains the whole engine and @@ -73,30 +83,38 @@ Note: To create an `.app` bundle like in the official builds, you need to use the template located in `misc/dist/osx_tools.app`. Typically, for an optimized -editor binary built with `target=release_debug`:: +editor binary built with `target=release_debug`: +``` cp -r misc/dist/osx_tools.app ./Godot.app mkdir -p Godot.app/Contents/MacOS cp bin/godot.osx.opt.tools.universal Godot.app/Contents/MacOS/Godot chmod +x Godot.app/Contents/MacOS/Godot +``` Compiling a headless/server build --------------------------------- To compile a *headless* build which provides editor functionality to export -projects in an automated manner, use:: +projects in an automated manner, use: +``` scons platform=server tools=yes target=release_debug --jobs=$(sysctl -n hw.logicalcpu) +``` To compile a debug *server* build which can be used with -`remote debugging tools ( doc_command_line_tutorial )`, use:: +`remote debugging tools ( doc_command_line_tutorial )`, use: +``` scons platform=server tools=no target=release_debug --jobs=$(sysctl -n hw.logicalcpu) +``` To compile a release *server* build which is optimized to run dedicated game servers, -use:: +use: +``` scons platform=server tools=no target=release --jobs=$(sysctl -n hw.logicalcpu) +``` Building export templates ------------------------- @@ -109,39 +127,49 @@ Official templates are universal binaries which support both Intel x86_64 and ARM64 architectures. You can also create export templates that support only one of those two architectures by leaving out the `lipo` step below. -- For Intel x86_64:: +- For Intel x86_64: +``` scons platform=osx tools=no target=release arch=x86_64 --jobs=$(sysctl -n hw.logicalcpu) scons platform=osx tools=no target=release_debug arch=x86_64 --jobs=$(sysctl -n hw.logicalcpu) +``` -- For ARM64 (Apple M1):: +- For ARM64 (Apple M1): +``` scons platform=osx tools=no target=release arch=arm64 --jobs=$(sysctl -n hw.logicalcpu) scons platform=osx tools=no target=release_debug arch=arm64 --jobs=$(sysctl -n hw.logicalcpu) +``` To support both architectures in a single "Universal 2" binary, run the above -two commands blocks and then use `lipo` to bundle them together:: +two commands blocks and then use `lipo` to bundle them together: +``` lipo -create bin/godot.osx.opt.x86_64 bin/godot.osx.opt.arm64 -output bin/godot.osx.opt.universal lipo -create bin/godot.osx.opt.debug.x86_64 bin/godot.osx.opt.debug.arm64 -output bin/godot.osx.opt.debug.universal +``` To create an `.app` bundle like in the official builds, you need to use the template located in `misc/dist/osx_template.app`. The release and debug builds should be placed in `osx_template.app/Contents/MacOS` with the names `godot_osx_release.64` and `godot_osx_debug.64` respectively. You can do so with the following commands (assuming a universal build, otherwise replace the -`.universal` extension with the one of your arch-specific binaries):: +`.universal` extension with the one of your arch-specific binaries): +``` cp -r misc/dist/osx_template.app . mkdir -p osx_template.app/Contents/MacOS cp bin/godot.osx.opt.universal osx_template.app/Contents/MacOS/godot_osx_release.64 cp bin/godot.osx.opt.debug.universal osx_template.app/Contents/MacOS/godot_osx_debug.64 chmod +x osx_template.app/Contents/MacOS/godot_osx* +``` You can then zip the `osx_template.app` folder to reproduce the `osx.zip` -template from the official Godot distribution:: +template from the official Godot distribution: +``` zip -q -9 -r osx.zip osx_template.app +``` Cross-compiling for macOS from Linux ------------------------------------ @@ -153,9 +181,11 @@ as a target. First, follow the instructions to install it: Clone the `OSXCross repository ( https://github.com/tpoechtrager/osxcross )` somewhere on your machine (or download a ZIP file and extract it somewhere), -e.g.:: +e.g.: +``` git clone --depth=1 https://github.com/tpoechtrager/osxcross.git "$HOME/osxcross" +``` 1. Follow the instructions to package the SDK: https://github.com/tpoechtrager/osxcross#packaging-the-sdk @@ -164,14 +194,20 @@ e.g.:: After that, you will need to define the `OSXCROSS_ROOT` as the path to the OSXCross installation (the same place where you cloned the -repository/extracted the zip), e.g.:: +repository/extracted the zip), e.g.: +``` export OSXCROSS_ROOT="$HOME/osxcross" +``` -Now you can compile with SCons like you normally would:: +Now you can compile with SCons like you normally would: +``` scons platform=osx +``` -If you have an OSXCross SDK version different from the one expected by the SCons buildsystem, you can specify a custom one with the `osxcross_sdk` argument:: +If you have an OSXCross SDK version different from the one expected by the SCons buildsystem, you can specify a custom one with the `osxcross_sdk` argument: +``` scons platform=osx osxcross_sdk=darwin15 +``` \ No newline at end of file diff --git a/development/compiling/compiling_for_uwp.md b/development/compiling/compiling_for_uwp.md index 4b1d499..28e7f1d 100644 --- a/development/compiling/compiling_for_uwp.md +++ b/development/compiling/compiling_for_uwp.md @@ -54,9 +54,11 @@ Set the `ANGLE_SRC_PATH` to the directory where you downloaded the ANGLE source code. The build process will also build ANGLE to produce the required DLLs for the selected architecture. -Once you're set, run the SCons command similarly to the other platforms:: +Once you're set, run the SCons command similarly to the other platforms: +``` C:\godot>scons platform=uwp +``` Creating UWP export templates ----------------------------- @@ -66,10 +68,12 @@ You need all three architectures with `debug` and `release` templates to be able to export. Open the command prompt for one architecture and run SCons twice (once for -each target):: +each target): +``` C:\godot>scons platform=uwp target=release_debug C:\godot>scons platform=uwp target=release +``` Repeat for the other architectures. @@ -84,14 +88,16 @@ under `winrt/10/src/Release_%arch%` (where `%arch%` can be `Win32`, putting them along with the executable. Add the files in the `uwp_template` folder to a ZIP. Rename the resulting -Zip according to the target/architecture of the template:: +Zip according to the target/architecture of the template: +``` uwp_x86_debug.zip uwp_x86_release.zip uwp_x64_debug.zip uwp_x64_release.zip uwp_arm_debug.zip uwp_arm_release.zip +``` Move those templates to the `[versionstring]\templates` folder in Godot settings path, where `versionstring` is the version of Godot you have compiled diff --git a/development/compiling/compiling_for_web.md b/development/compiling/compiling_for_web.md index 65d9132..83d226b 100644 --- a/development/compiling/compiling_for_web.md +++ b/development/compiling/compiling_for_web.md @@ -35,18 +35,22 @@ and `source ./emsdk_env.sh`/`emsdk_env.bat`. Open a terminal and navigate to the root directory of the engine source code. Then instruct SCons to build the JavaScript platform. Specify `target` as -either `release` for a release build or `release_debug` for a debug build:: +either `release` for a release build or `release_debug` for a debug build: +``` scons platform=javascript tools=no target=release scons platform=javascript tools=no target=release_debug +``` By default, the `JavaScript singleton ( doc_javascript_eval )` will be built into the engine. Official export templates also have the JavaScript singleton enabled. Since `eval()` calls can be a security concern, the -`javascript_eval` option can be used to build without the singleton:: +`javascript_eval` option can be used to build without the singleton: +``` scons platform=javascript tools=no target=release javascript_eval=no scons platform=javascript tools=no target=release_debug javascript_eval=no +``` The engine will now be compiled to WebAssembly by Emscripten. Once finished, the resulting file will be placed in the `bin` subdirectory. Its name is @@ -54,13 +58,17 @@ the resulting file will be placed in the `bin` subdirectory. Its name is for debug. Finally, rename the zip archive to `webassembly_release.zip` for the -release template:: +release template: +``` mv bin/godot.javascript.opt.zip bin/webassembly_release.zip +``` -And `webassembly_debug.zip` for the debug template:: +And `webassembly_debug.zip` for the debug template: +``` mv bin/godot.javascript.opt.debug.zip bin/webassembly_debug.zip +``` Threads and GDNative -------------------- @@ -70,37 +78,45 @@ performance and compatibility reasons. See the `export page ( doc_javascript_export_options )` for more info. You can build the export templates using the option `threads_enabled=yes` or -`gdnative_enabled=yes` to enable threads or GDNative support:: +`gdnative_enabled=yes` to enable threads or GDNative support: +``` scons platform=javascript tools=no threads_enabled=yes target=release scons platform=javascript tools=no threads_enabled=yes target=release_debug scons platform=javascript tools=no gdnative_enabled=yes target=release scons platform=javascript tools=no gdnative_enabled=yes target=release_debug +``` Once finished, the resulting file will be placed in the `bin` subdirectory. Its name will have either the `.threads` or `.gdnative` suffix. Finally, rename the zip archives to `webassembly_release_threads.zip` and -`webassembly_release_gdnative.zip` for the release template:: +`webassembly_release_gdnative.zip` for the release template: +``` mv bin/godot.javascript.opt.threads.zip bin/webassembly_threads_release.zip mv bin/godot.javascript.opt.gdnative.zip bin/webassembly_gdnative_release.zip +``` And `webassembly_debug_threads.zip` and `webassembly_debug_gdnative.zip` for -the debug template:: +the debug template: +``` mv bin/godot.javascript.opt.debug.threads.zip bin/webassembly_threads_debug.zip mv bin/godot.javascript.opt.debug.gdnative.zip bin/webassembly_gdnative_debug.zip +``` Building the Editor ------------------- It is also possible to build a version of the Godot editor that can run in the browser. The editor version requires threads support and is not recommended -over the native build. You can build the editor with:: +over the native build. You can build the editor with: +``` scons platform=javascript tools=yes threads_enabled=yes target=release_debug +``` Once finished, the resulting file will be placed in the `bin` subdirectory. Its name will be `godot.javascript.opt.tools.threads.zip`. You can upload the diff --git a/development/compiling/compiling_for_windows.md b/development/compiling/compiling_for_windows.md index a9b0c1d..7019355 100644 --- a/development/compiling/compiling_for_windows.md +++ b/development/compiling/compiling_for_windows.md @@ -28,16 +28,20 @@ For compiling under Windows, the following is required: Note: If you have `Scoop ( https://scoop.sh/ )` installed, you can easily - install MinGW and other dependencies using the following command:: + install MinGW and other dependencies using the following command: +``` scoop install gcc python scons make +``` Note: If you have `MSYS2 ( https://www.msys2.org/ )` installed, you can easily - install MinGW and other dependencies using the following command:: + install MinGW and other dependencies using the following command: +``` pacman -S mingw-w64-x86_64-python3-pip mingw-w64-x86_64-gcc \ mingw-w64-i686-python3-pip mingw-w64-i686-gcc make +``` For each MSYS2 MinGW subsystem, you should then run `pip3 install scons` in its shell. @@ -52,9 +56,11 @@ See also: Setting up SCons ---------------- -To install SCons, open the command prompt and run the following command:: +To install SCons, open the command prompt and run the following command: +``` python -m pip install scons +``` If you are prompted with the message `Defaulting to user installation because normal site-packages is not @@ -134,13 +140,17 @@ Running SCons ~~~~~~~~~~~~~ After opening a command prompt, change to the root directory of -the engine source code (using `cd`) and type:: +the engine source code (using `cd`) and type: +``` C:\godot> scons platform=windows +``` -You can specify a number of CPU threads to use to speed up the build:: +You can specify a number of CPU threads to use to speed up the build: +``` C:\godot> scons -j6 platform=windows +``` In general, it is OK to have at least as many threads compiling Godot as you have cores in your CPU, if not one or two more. Feel free to add the `-j` @@ -186,9 +196,11 @@ Folder-based editors don't require any particular setup to start working with Go codebase. To edit projects with Visual Studio they need to be set up as a solution. You can create a Visual Studio solution via SCons by running SCons with -the `vsproj=yes` parameter, like this:: +the `vsproj=yes` parameter, like this: +``` scons p=windows vsproj=yes +``` You will be able to open Godot's source in a Visual Studio solution now, and able to build Godot using Visual Studio's **Build** button. @@ -207,20 +219,20 @@ here are some known ones: +----------------+--------------------------------------------------------------+ | **Arch Linux** | Install `mingw-w64-gcc from the AUR`. | +----------------+--------------------------------------------------------------+ -| **Debian** / | :: | +| **Debian** / | | | **Ubuntu** | | | | apt install mingw-w64 | +----------------+--------------------------------------------------------------+ -| **Fedora** | :: | +| **Fedora** | | | | | | | dnf install mingw64-gcc-c++ mingw64-winpthreads-static \ | | | mingw32-gcc-c++ mingw32-winpthreads-static | +----------------+--------------------------------------------------------------+ -| **macOS** | :: | +| **macOS** | | | | | | | brew install mingw-w64 | +----------------+--------------------------------------------------------------+ -| **Mageia** | :: | +| **Mageia** | | | | | | | urpmi mingw64-gcc-c++ mingw64-winpthreads-static \ | | | mingw32-gcc-c++ mingw32-winpthreads-static | @@ -229,24 +241,30 @@ here are some known ones: .. _mingw-w64-gcc from the AUR: https://aur.archlinux.org/packages/mingw-w64-gcc/ Before attempting the compilation, SCons will check for -the following binaries in your `PATH` environment variable:: +the following binaries in your `PATH` environment variable: +``` i686-w64-mingw32-gcc x86_64-w64-mingw32-gcc +``` If the binaries are not located in the `PATH` (e.g. `/usr/bin`), you can define the following environment variables to give a hint to -the build system:: +the build system: +``` export MINGW32_PREFIX="/path/to/i686-w64-mingw32-" export MINGW64_PREFIX="/path/to/x86_64-w64-mingw32-" +``` To make sure you are doing things correctly, executing the following in the shell should result in a working compiler (the version output may -differ based on your system):: +differ based on your system): +``` ${MINGW32_PREFIX}gcc --version # i686-w64-mingw32-gcc (GCC) 6.1.0 20160427 (Mageia MinGW 6.1.0-1.mga6) +``` Troubleshooting ~~~~~~~~~~~~~~~ @@ -256,43 +274,53 @@ Cross-compiling from some Ubuntu versions may lead to due to a default configuration lacking support for POSIX threading. You can change that configuration following those instructions, -for 64-bit:: +for 64-bit: +``` sudo update-alternatives --config x86_64-w64-mingw32-gcc sudo update-alternatives --config x86_64-w64-mingw32-g++ +``` -And for 32-bit:: +And for 32-bit: +``` sudo update-alternatives --config i686-w64-mingw32-gcc sudo update-alternatives --config i686-w64-mingw32-g++ +``` Creating Windows export templates --------------------------------- Windows export templates are created by compiling Godot without the editor, -with the following flags:: +with the following flags: +``` C:\godot> scons platform=windows tools=no target=release_debug bits=32 C:\godot> scons platform=windows tools=no target=release bits=32 C:\godot> scons platform=windows tools=no target=release_debug bits=64 C:\godot> scons platform=windows tools=no target=release bits=64 +``` If you plan on replacing the standard export templates, copy these to the following location, replacing `( version )` with the version identifier -(such as `3.1.1.stable` or `3.2.dev`):: +(such as `3.1.1.stable` or `3.2.dev`): +``` %USERPROFILE%\AppData\Roaming\Godot\templates\\ +``` -With the following names:: +With the following names: +``` windows_32_debug.exe windows_32_release.exe windows_64_debug.exe windows_64_release.exe +``` However, if you are using custom modules or custom engine code, you may instead want to configure your binaries as custom export templates diff --git a/development/compiling/compiling_for_x11.md b/development/compiling/compiling_for_x11.md index 8bc6863..837e742 100644 --- a/development/compiling/compiling_for_x11.md +++ b/development/compiling/compiling_for_x11.md @@ -41,60 +41,60 @@ See also: Distro-specific one-liners ^^^^^^^^^^^^^^^^^^^^^^^^^^ +------------------+-----------------------------------------------------------------------------------------------------------+ -| **Alpine Linux** | :: | +| **Alpine Linux** | | | | | | | apk add scons pkgconf gcc g++ libx11-dev libxcursor-dev libxinerama-dev libxi-dev libxrandr-dev \ | | | mesa-dev libexecinfo-dev eudev-dev alsa-lib-dev pulseaudio-dev | +------------------+-----------------------------------------------------------------------------------------------------------+ -| **Arch Linux** | :: | +| **Arch Linux** | | | | | | | pacman -S --needed scons pkgconf gcc libxcursor libxinerama libxi libxrandr mesa glu libglvnd \ | | | alsa-lib pulseaudio yasm | +------------------+-----------------------------------------------------------------------------------------------------------+ -| **Debian** / | :: | +| **Debian** / | | | **Ubuntu** | | | | sudo apt-get install build-essential scons pkg-config libx11-dev libxcursor-dev libxinerama-dev \ | | | libgl1-mesa-dev libglu-dev libasound2-dev libpulse-dev libudev-dev libxi-dev libxrandr-dev yasm | +------------------+-----------------------------------------------------------------------------------------------------------+ -| **Fedora** | :: | +| **Fedora** | | | | | | | sudo dnf install scons pkgconfig libX11-devel libXcursor-devel libXrandr-devel libXinerama-devel \ | | | libXi-devel mesa-libGL-devel mesa-libGLU-devel alsa-lib-devel pulseaudio-libs-devel \ | | | libudev-devel yasm gcc-c++ libstdc++-static libatomic-static | +------------------+-----------------------------------------------------------------------------------------------------------+ -| **FreeBSD** | :: | +| **FreeBSD** | | | | | | | sudo pkg install py37-scons pkgconf xorg-libraries libXcursor libXrandr libXi xorgproto libGLU \ | | | alsa-lib pulseaudio yasm | | | | +------------------+-----------------------------------------------------------------------------------------------------------+ -| **Gentoo** | :: | +| **Gentoo** | | | | | | | emerge -an dev-util/scons x11-libs/libX11 x11-libs/libXcursor x11-libs/libXinerama x11-libs/libXi \ | | | media-libs/mesa media-libs/glu media-libs/alsa-lib media-sound/pulseaudio dev-lang/yasm | +------------------+-----------------------------------------------------------------------------------------------------------+ -| **Mageia** | :: | +| **Mageia** | | | | | | | urpmi scons task-c++-devel pkgconfig "pkgconfig(alsa)" "pkgconfig(glu)" "pkgconfig(libpulse)" \ | | | "pkgconfig(udev)" "pkgconfig(x11)" "pkgconfig(xcursor)" "pkgconfig(xinerama)" "pkgconfig(xi)" \ | | | "pkgconfig(xrandr)" yasm | +------------------+-----------------------------------------------------------------------------------------------------------+ -| **OpenBSD** | :: | +| **OpenBSD** | | | | | | | pkg_add python scons llvm yasm | +------------------+-----------------------------------------------------------------------------------------------------------+ -| **openSUSE** | :: | +| **openSUSE** | | | | | | | sudo zypper install scons pkgconfig libX11-devel libXcursor-devel libXrandr-devel libXinerama-devel \ | | | libXi-devel Mesa-libGL-devel alsa-devel libpulse-devel libudev-devel libGLU1 yasm | +------------------+-----------------------------------------------------------------------------------------------------------+ -| **NetBSD** | :: | +| **NetBSD** | | | | | | | pkg_add pkg-config py37-scons yasm | | | | | | For audio support, you can optionally install `pulseaudio`. | +------------------+-----------------------------------------------------------------------------------------------------------+ -| **Solus** | :: | +| **Solus** | | | | | | | sudo eopkg install -c system.devel scons libxcursor-devel libxinerama-devel libxi-devel \ | | | libxrandr-devel mesalib-devel libglu alsa-lib-devel pulseaudio-devel yasm | @@ -105,9 +105,9 @@ Compiling Start a terminal, go to the root dir of the engine source code and type: -:: - +``` scons -j8 platform=x11 +``` A good rule of thumb for the `-j` (*jobs*) flag, is to have at least as many threads compiling Godot as you have cores in your CPU, if not one or two more. @@ -123,9 +123,9 @@ Note: If you wish to compile using Clang rather than GCC, use this command: - :: - +``` scons platform=x11 use_llvm=yes +``` Using Clang appears to be a requirement for OpenBSD, otherwise fonts would not build. @@ -150,19 +150,25 @@ Compiling a headless/server build --------------------------------- To compile a *headless* build which provides editor functionality to export -projects in an automated manner, use:: +projects in an automated manner, use: +``` scons -j8 platform=server tools=yes target=release_debug +``` To compile a debug *server* build which can be used with -`remote debugging tools ( doc_command_line_tutorial )`, use:: +`remote debugging tools ( doc_command_line_tutorial )`, use: +``` scons -j8 platform=server tools=no target=release_debug +``` To compile a *server* build which is optimized to run dedicated game servers, -use:: +use: +``` scons -j8 platform=server tools=no target=release +``` Building export templates ------------------------- @@ -181,35 +187,35 @@ following parameters: - (32 bits) -:: - +``` scons platform=x11 tools=no target=release bits=32 scons platform=x11 tools=no target=release_debug bits=32 +``` - (64 bits) -:: - +``` scons platform=x11 tools=no target=release bits=64 scons platform=x11 tools=no target=release_debug bits=64 +``` Note that cross-compiling for the opposite bits (64/32) as your host platform is not always straight-forward and might need a chroot environment. To create standard export templates, the resulting files must be copied to: -:: - +``` $HOME/.local/share/godot/templates/[gd-version]/ +``` and named like this (even for \*BSD which is seen as "Linux X11" by Godot): -:: - +``` linux_x11_32_debug linux_x11_32_release linux_x11_64_debug linux_x11_64_release +``` However, if you are writing your custom modules or custom C++ code, you might instead want to configure your binaries as custom export templates @@ -232,9 +238,11 @@ the default GCC + GNU ld setup: - Clang tends to give more useful error messages compared to GCC. To do so, install Clang and the `lld` package from your distribution's package manager -then use the following SCons command:: +then use the following SCons command: +``` scons platform=x11 use_llvm=yes use_lld=yes +``` After the build is completed, a new binary with a `.llvm` suffix will be created in the `bin/` folder. @@ -256,9 +264,11 @@ to get even faster builds. - Use `cd` to reach the extracted Pyston folder from a terminal, then run `./pyston -m pip install scons` to install SCons within Pyston. - To make SCons via Pyston easier to run, create a symbolic link of its wrapper - script to a location in your `PATH` environment variable:: + script to a location in your `PATH` environment variable: +``` ln -s ~/.local/opt/pyston/bin/scons ~/.local/bin/pyston-scons +``` - Instead of running `scons ( build arguments )`, run `pyston-scons ( build arguments )` to compile Godot. diff --git a/development/compiling/compiling_with_script_encryption_key.md b/development/compiling/compiling_with_script_encryption_key.md index 0921cd1..f1e49f6 100644 --- a/development/compiling/compiling_with_script_encryption_key.md +++ b/development/compiling/compiling_with_script_encryption_key.md @@ -30,16 +30,16 @@ Step by step Alternatively, you can generate it yourself using `OpenSSL ( https://www.openssl.org/ )` command-line tools: - :: - +``` openssl rand -hex 32 > godot.gdkey +``` The output in `godot.gdkey` should be similar to: - :: - +``` # NOTE: Do not use the key below! Generate your own key instead. aeb1bc56aaf580cc31784e9c41551e9ed976ecba10d315db591e749f3f64890f +``` You can generate the key without redirecting the output to a file, but that way you can minimize the risk of exposing the key. @@ -76,8 +76,7 @@ If you get an error like below, it means the key wasn't properly included in your Godot build. Godot is encrypting the scripts during export, but can't read them at runtime. -:: - +``` ERROR: open_and_parse: Condition "String::md5(md5.digest) != String::md5(md5d)" is true. Returning: ERR_FILE_CORRUPT At: core/io/file_access_encrypted.cpp:103 ERROR: load_byte_code: Condition ' err ' is true. returned: err @@ -98,3 +97,4 @@ them at runtime. At: core/object.cpp:2081 ERROR: clear: Resources Still in use at Exit! At: core/resource.cpp:425 +``` \ No newline at end of file diff --git a/development/compiling/cross-compiling_for_ios_on_linux.md b/development/compiling/cross-compiling_for_ios_on_linux.md index fed5266..fbeb6dd 100644 --- a/development/compiling/cross-compiling_for_ios_on_linux.md +++ b/development/compiling/cross-compiling_for_ios_on_linux.md @@ -53,69 +53,69 @@ darling-dmg Clone the repository on your machine: -:: - +``` $ git clone https://github.com/darlinghq/darling-dmg.git +``` Build it: -:: - +``` $ cd darling-dmg $ mkdir build $ cd build $ cmake .. -DCMAKE_BUILD_TYPE=Release $ make -j 4 # The number is the amount of cores your processor has, for faster build $ cd ../.. +``` Preparing the SDK ~~~~~~~~~~~~~~~~~ Mount the XCode image: -:: - +``` $ mkdir xcode $ ./darling-dmg/build/darling-dmg /path/to/Xcode_7.1.1.dmg xcode [...] Everything looks OK, disk mounted +``` Extract the iOS SDK: -:: - +``` $ mkdir -p iPhoneSDK/iPhoneOS9.1.sdk $ cp -r xcode/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/* iPhoneSDK/iPhoneOS9.1.sdk $ cp -r xcode/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/include/c++/* iPhoneSDK/iPhoneOS9.1.sdk/usr/include/c++ $ fusermount -u xcode # unmount the image +``` Pack the SDK: -:: - +``` $ cd iPhoneSDK $ tar -cf - * | xz -9 -c - > iPhoneOS9.1.sdk.tar.xz +``` Toolchain ~~~~~~~~~ Build cctools: -:: - +``` $ git clone https://github.com/tpoechtrager/cctools-port.git $ cd cctools-port/usage_examples/ios_toolchain $ ./build.sh /path/iPhoneOS9.1.sdk.tar.xz arm64 +``` Copy the tools to a nicer place. Note that the SCons scripts for building will look under `usr/bin` inside the directory you provide for the toolchain binaries, so you must copy to such subdirectory, akin to the following commands: -:: - +``` $ mkdir -p /home/user/iostoolchain/usr $ cp -r target/bin /home/user/iostoolchain/usr/ +``` Now you should have the iOS toolchain binaries in `/home/user/iostoolchain/usr/bin`. @@ -131,17 +131,17 @@ SCons build command. For the iPhone platform to be detected, you need the `OSXCROSS_IOS` environment variable defined to anything. -:: - +``` $ export OSXCROSS_IOS=anything +``` Now you can compile for iPhone using SCons like the standard Godot way, with some additional arguments to provide the correct paths: -:: - +``` $ scons -j 4 platform=iphone arch=arm target=release_debug IPHONESDK="/path/to/iPhoneSDK" IPHONEPATH="/path/to/iostoolchain" ios_triple="arm-apple-darwin11-" $ scons -j 4 platform=iphone arch=arm64 target=release_debug IPHONESDK="/path/to/iPhoneSDK" IPHONEPATH="/path/to/iostoolchain" ios_triple="arm-apple-darwin11-" +``` Producing fat binaries ~~~~~~~~~~~~~~~~~~~~~~ @@ -151,11 +151,10 @@ Apple requires a fat binary with both architectures (`armv7` and `arm-apple-darwin11-lipo` executable. The following example assumes you are in the root Godot source directory: -:: - +``` $ /path/to/iostoolchain/usr/bin/arm-apple-darwin11-lipo -create bin/libgodot.iphone.opt.debug.arm.a bin/libgodot.iphone.opt.debug.arm64.a -output bin/libgodot.iphone.debug.fat.a $ /path/to/iostoolchain/usr/bin/arm-apple-darwin11-lipo -create bin/libgodot_camera_module.iphone.opt.debug.arm.a bin/libgodot_camera_module.iphone.opt.debug.arm64.a -output bin/libgodot_camera_module.iphone.debug.fat.a $ /path/to/iostoolchain/usr/bin/arm-apple-darwin11-lipo -create bin/libgodot_arkit_module.iphone.opt.debug.arm.a bin/libgodot_arkit_module.iphone.opt.debug.arm64.a -output bin/libgodot_arkit_module.iphone.debug.fat.a - +``` Then you will have iOS fat binaries in `bin` directory. diff --git a/development/compiling/getting_source.md b/development/compiling/getting_source.md index 8a78dbf..f12b0fb 100644 --- a/development/compiling/getting_source.md +++ b/development/compiling/getting_source.md @@ -28,24 +28,26 @@ Afterwards, to get the latest development version of the Godot source code If you are using the `git` command line client, this is done by entering the following in a terminal: -:: - +``` git clone https://github.com/godotengine/godot.git # You can add the --depth 1 argument to omit the commit history. # Faster, but not all Git operations (like blame) will work. +``` For any stable release, visit the `release page ( https://github.com/godotengine/godot/releases )` and click on the link for the release you want. You can then download and extract the source from the download link on the page. With `git`, you can also clone a stable release by specifying its branch or tag -after the `--branch` (or just `-b`) argument:: +after the `--branch` (or just `-b`) argument: +``` # Clone the continuously maintained stable branch (`3.x` as of writing). git clone https://github.com/godotengine/godot.git -b 3.x # Clone the `3.2.3-stable` tag. This is a fixed revision that will never change. git clone https://github.com/godotengine/godot.git -b 3.2.3-stable +``` There are also generally branches besides `master` for each major version. diff --git a/development/compiling/introduction_to_the_buildsystem.md b/development/compiling/introduction_to_the_buildsystem.md index 9dcc43c..f98b84b 100644 --- a/development/compiling/introduction_to_the_buildsystem.md +++ b/development/compiling/introduction_to_the_buildsystem.md @@ -59,8 +59,9 @@ SCons is invoked by just calling `scons`. If no platform is specified, SCons will detect the target platform automatically based on the host platform. It will then start building for the target platform right away. -To list the available target platforms, use `scons platform=list`:: +To list the available target platforms, use `scons platform=list`: +``` scons platform=list scons: Reading SConscript files ... The following platforms are available: @@ -72,13 +73,14 @@ To list the available target platforms, use `scons platform=list`:: x11 Please run SCons again and select a valid platform: platform= +``` To build for a platform (for example, x11), run with the `platform=` (or `p=` to make it short) argument: -:: - +``` scons platform=x11 +``` This will start the build process, which will take a while. If you want SCons to build faster, use the `-j .[opt].[tools/debug].[extension] +``` -For the previous build attempt, the result would look like this:: +For the previous build attempt, the result would look like this: +``` ls bin bin/godot.x11.tools.64 +``` This means that the binary is for X11, is not optimized, has tools (the whole editor) compiled in, and is meant for 64 bits. A Windows binary with the same configuration will look like this: -.. code-block:: console - +``` C:\godot> dir bin/ godot.windows.tools.64.exe +``` Copy that binary to any location you like, as it contains the project manager, editor and all means to execute the game. However, it lacks the data to export @@ -133,10 +139,9 @@ disabled for everything else. Disabling tools produces a binary that can run projects but that does not include the editor or the project manager. -:: - +``` scons platform= tools=yes/no - +``` Target @@ -154,9 +159,9 @@ Target controls optimization and debug flags. Each mode means: `tools=yes`, as the editor requires some debug functionality and run-time checks to run. -:: - +``` scons platform= target=debug/release_debug/release +``` This flag appends the `.debug` suffix (for debug), or `.tools` (for debug with tools enabled). When optimization is enabled (release), it appends @@ -173,9 +178,9 @@ else. - **64**: Build binaries for 64-bit platforms. - **default**: Build for the architecture that matches the host platform. -:: - +``` scons platform= bits=default/32/64 +``` This flag appends `.32` or `.64` suffixes to resulting binaries when relevant. If `bits=default` is used, the suffix will match the detected @@ -197,9 +202,9 @@ 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: @@ -246,14 +251,14 @@ Using a file The default `custom.py` file can be created at the root of the Godot Engine source to initialize any SCons build options passed via the command line: -.. code-block:: python - +``` # custom.py optimize = "size" module_mono_enabled = "yes" use_llvm = "yes" extra_suffix = "game_title" +``` You can also disable some of the builtin modules before compiling, saving some time it takes to build the engine. See `doc_optimizing_for_size` page for more details. @@ -269,9 +274,9 @@ See also: Another custom file can be specified explicitly with the `profile` command line option, both overriding the default build configuration: -.. code-block:: shell - +``` scons profile=path/to/custom.py +``` Note: Build options set from the file can be overridden by the command line @@ -279,8 +284,7 @@ Note: It's also possible to override the options conditionally: -.. code-block:: python - +``` # custom.py import version @@ -290,6 +294,7 @@ It's also possible to override the options conditionally: pass elif version.major == 4: pass +``` Using the SCONSFLAGS ^^^^^^^^^^^^^^^^^^^^ @@ -324,8 +329,7 @@ If you download the official export templates package and unzip it, you will notice that most files are optimized binaries or packages for each platform: -.. code-block:: none - +``` android_debug.apk android_release.apk webassembly_debug.zip @@ -342,6 +346,7 @@ platform: windows_32_release.exe windows_64_debug.exe windows_64_release.exe +``` To create those yourself, follow the instructions detailed for each platform in this same tutorial section. Each platform explains how to diff --git a/development/compiling/optimizing_for_size.md b/development/compiling/optimizing_for_size.md index bffe857..46a174b 100644 --- a/development/compiling/optimizing_for_size.md +++ b/development/compiling/optimizing_for_size.md @@ -30,9 +30,9 @@ If you build Windows (MinGW), Linux or macOS binaries from source, remember to strip debug symbols from binaries by installing the `strip` package from your distribution then running: -:: - +``` strip path/to/godot.binary +``` On Windows, `strip.exe` is included in most MinGW toolchain setups. @@ -59,9 +59,9 @@ Optimizing for size instead of speed Godot 3.1 onwards allows compiling using size optimizations (instead of speed). To enable this, set the `optimize` flag to `size`: -:: - +``` scons p=windows target=release tools=no optimize=size +``` Some platforms such as WebAssembly already use this mode by default. @@ -77,9 +77,9 @@ terms of performance and file size. It works by eliminating duplicate template functions and unused code. It can currently be used with the GCC and MSVC compilers: -:: - +``` scons p=windows target=release tools=no use_lto=yes +``` Linking becomes much slower and more RAM-consuming with this option, so it should be used only for release builds: @@ -98,9 +98,9 @@ Disabling 3D For 2D games, having the whole 3D engine available usually makes no sense. Because of this, there is a build flag to disable it: -:: - +``` scons p=windows target=release tools=no disable_3d=yes +``` Tools must be disabled in order to use this flag, as the editor is not designed to operate without 3D support. Without it, the binary size can be reduced @@ -116,9 +116,9 @@ Disabling advanced GUI objects Most small games don't require complex GUI controls such as Tree, ItemList, TextEdit or GraphEdit. They can be disabled using a build flag: -:: - +``` scons p=windows target=release tools=no disable_advanced_gui=yes +``` This is everything that will be disabled: @@ -155,17 +155,17 @@ Disabling unwanted modules A lot of Godot's functions are offered as modules. You can see a list of modules with the following command: -:: - +``` scons --help +``` The list of modules that can be disabled will appear, together with all build options. If you are working on a simple 2D game, you could disable a lot of them: -:: - +``` scons p=windows target=release tools=no module_arkit_enabled=no module_assimp_enabled=no module_bmp_enabled=no module_bullet_enabled=no module_camera_enabled=no module_csg_enabled=no module_dds_enabled=no module_enet_enabled=no module_etc_enabled=no module_gdnative_enabled=no module_gridmap_enabled=no module_hdr_enabled=no module_jsonrpc_enabled=no module_mbedtls_enabled=no module_mobile_vr_enabled=no module_opensimplex_enabled=no module_opus_enabled=no module_pvr_enabled=no module_recast_enabled=no module_regex_enabled=no module_squish_enabled=no module_svg_enabled=no module_tga_enabled=no module_theora_enabled=no module_tinyexr_enabled=no module_upnp_enabled=no module_vhacd_enabled=no module_vorbis_enabled=no module_webm_enabled=no module_webrtc_enabled=no module_websocket_enabled=no module_xatlas_unwrap_enabled=no +``` If this proves not to work for your use case, you should review the list of modules and see which ones you actually still need for your game (e.g. you @@ -176,8 +176,7 @@ Alternatively, you can supply a list of disabled modules by creating `custom.py` at the root of the source, with the contents similar to the following: -.. code-block:: python - +``` # custom.py module_arkit_enabled = "no" @@ -212,6 +211,7 @@ following: module_webrtc_enabled = "no" module_websocket_enabled = "no" module_xatlas_unwrap_enabled = "no" +``` See also: diff --git a/development/cpp/binding_to_external_libraries.md b/development/cpp/binding_to_external_libraries.md index e190286..c85c868 100644 --- a/development/cpp/binding_to_external_libraries.md +++ b/development/cpp/binding_to_external_libraries.md @@ -13,14 +13,13 @@ a speech synthesis (text-to-speech) library written in C++. To bind to an external library, set up a module directory similar to the Summator example: -.. code-block:: none - +``` godot/modules/tts/ +``` Next, you will create a header file with a simple TTS class: -.. code-block:: cpp - +``` /* tts.h */ #ifndef GODOT_TTS_H @@ -41,11 +40,11 @@ Next, you will create a header file with a simple TTS class: }; #endif // GODOT_TTS_H +``` And then you'll add the cpp file. -.. code-block:: cpp - +``` /* tts.cpp */ #include "tts.h" @@ -66,14 +65,15 @@ And then you'll add the cpp file. TTS::TTS() { festival_initialize(true, 210000); //not the best way to do it as this should only ever be called once. } +``` Just as before, the new class needs to be registered somehow, so two more files need to be created: -.. code-block:: none - +``` register_types.h register_types.cpp +``` .. important:: These files must be in the top-level folder of your module (next to your @@ -81,16 +81,15 @@ need to be created: These files should contain the following: -.. code-block:: cpp - +``` /* register_types.h */ void register_tts_types(); void unregister_tts_types(); /* yes, the word in the middle must be the same as the module folder name */ +``` -.. code-block:: cpp - +``` /* register_types.cpp */ #include "register_types.h" @@ -105,28 +104,29 @@ These files should contain the following: void unregister_tts_types() { // Nothing to do here in this example. } +``` Next, you need to create a `SCsub` file so the build system compiles this module: -.. code-block:: python - +``` # SCsub Import('env') env_tts = env.Clone() env_tts.add_source_files(env.modules_sources, "*.cpp") # Add all cpp files to the build +``` You'll need to install the external library on your machine to get the .a library files. See the library's official documentation for specific instructions on how to do this for your operation system. We've included the installation commands for Linux below, for reference. -.. code-block:: shell - +``` sudo apt-get install festival festival-dev <-- Installs festival and speech_tools libraries apt-cache search festvox-* <-- Displays list of voice packages sudo apt-get install festvox-don festvox-rablpc16k festvox-kallpc16k festvox-kdlpc16k <-- Installs voices +``` .. important:: The voices that Festival uses (and any other potential external/3rd-party @@ -139,18 +139,18 @@ files accessible to the compiler, while also keeping the module code self-contai festival and speech_tools libraries can be installed from the modules/tts/ directory via git using the following commands: -.. code-block:: shell - +``` git clone https://github.com/festvox/festival git clone https://github.com/festvox/speech_tools +``` If you don't want the external repository source files committed to your repository, you can link to them instead by adding them as submodules (from within the modules/tts/ directory), as seen below: -.. code-block:: shell - +``` git submodule add https://github.com/festvox/festival git submodule add https://github.com/festvox/speech_tools +``` .. important:: Please note that Git submodules are not used in the Godot repository. If @@ -161,8 +161,7 @@ can link to them instead by adding them as submodules (from within the modules/t To add include directories for the compiler to look at you can append it to the environment's paths: -.. code-block:: python - +``` # These paths are relative to /modules/tts/ env_tts.Append(CPPPATH=["speech_tools/include", "festival/src/include"]) @@ -177,13 +176,13 @@ environment's paths: # Check with the documentation of the external library to see which library # files should be included/linked. env.Append(LIBS=['Festival', 'estools', 'estbase', 'eststring']) +``` If you want to add custom compiler flags when building your module, you need to clone `env` first, so it won't add those flags to whole Godot build (which can cause errors). Example `SCsub` with custom flags: -.. code-block:: python - +``` # SCsub Import('env') @@ -195,11 +194,11 @@ Example `SCsub` with custom flags: # If you need to, you can: # - Append CFLAGS for C code only. # - Append CXXFLAGS for C++ code only. +``` The final module should look like this: -.. code-block:: none - +``` godot/modules/tts/festival/ godot/modules/tts/libpath/libestbase.a godot/modules/tts/libpath/libestools.a @@ -212,17 +211,18 @@ The final module should look like this: godot/modules/tts/register_types.h godot/modules/tts/register_types.cpp godot/modules/tts/SCsub +``` Using the module ---------------- You can now use your newly created module from any script: -:: - +``` var t = TTS.new() var script = "Hello world. This is a test!" var is_spoken = t.say_text(script) print('is_spoken: ', is_spoken) +``` And the output will be `is_spoken: True` if the text is spoken. diff --git a/development/cpp/common_engine_methods_and_macros.md b/development/cpp/common_engine_methods_and_macros.md index 8385c25..eab4f68 100644 --- a/development/cpp/common_engine_methods_and_macros.md +++ b/development/cpp/common_engine_methods_and_macros.md @@ -10,8 +10,7 @@ but it can also be useful for those writing custom C++ modules. Print text ---------- -.. code-block:: cpp - +``` // Prints a message to standard output. print_line("Message"); @@ -27,6 +26,7 @@ Print text // This can be used to avoid spamming the console output. ERR_PRINT_ONCE("Message"); WARN_PRINT_ONCE("Message"); +``` If you need to add placeholders in your messages, use format strings as described below. @@ -37,8 +37,7 @@ Format a string The `vformat()` function returns a formatted `String`. It behaves in a way similar to C's `sprintf()`: -.. code-block:: cpp - +``` vformat("My name is %s.", "Godette"); vformat("%d bugs on the wall!", 1234); vformat("Pi is approximately %f.", 3.1416); @@ -47,6 +46,7 @@ in a way similar to C's `sprintf()`: // You may need to do this if passing the result as an argument // to a method that expects a `const char *` instead of a String. vformat("My name is %s.", "Godette").c_str(); +``` In most cases, try to use `vformat()` instead of string concatenation as it makes for more readable code. @@ -56,13 +56,13 @@ Convert an integer or float to a string This is mainly useful when printing numbers directly. -.. code-block:: cpp - +``` // Prints "42" using integer-to-string conversion. print_line(itos(42)); // Prints "123.45" using real-to-string conversion. print_line(rtos(123.45)); +``` Internationalize a string ------------------------- @@ -77,20 +77,20 @@ There are two types of internationalization in Godot's codebase: projects if they provide a translation for the given string. This kind of translation shouldn't be used in editor-only code. -.. code-block:: cpp - +``` // Returns the translated string that matches the user's locale settings. // Translations are located in `editor/translations`. // The localization template is generated automatically; don't modify it. TTR("Exit the editor?"); +``` To insert placeholders in localizable strings, wrap the localization macro in a `vformat()` call as follows: -.. code-block:: cpp - +``` String file_path = "example.txt"; vformat(TTR("Couldn't open \"%s\" for reading."), file_path); +``` Note: @@ -106,14 +106,14 @@ Clamp a value Godot provides macros for clamping a value with a lower bound (`MAX`), an upper bound (`MIN`) or both (`CLAMP`): -.. code-block:: cpp - +``` int a = 3; int b = 5; MAX(b, 6); // 6 MIN(2, a); // 2 CLAMP(a, 10, 30); // 10 +``` This works with any type that can be compared to other values (like `int` and `float`). @@ -124,14 +124,14 @@ Microbenchmarking If you want to benchmark a piece of code but don't know how to use a profiler, use this snippet: -.. code-block:: cpp - +``` uint64_t begin = OS::get_singleton()->get_ticks_usec(); // Your code here... uint64_t end = OS::get_singleton()->get_ticks_usec(); print_line(vformat("Snippet took %d microseconds", end - begin)); +``` This will print the time spent between the `begin` declaration and the `end` declaration. @@ -149,8 +149,7 @@ Get project/editor settings There are four macros available for this: -.. code-block:: cpp - +``` // Returns the specified project setting's value, // defaulting to `false` if it doesn't exist. GLOBAL_DEF("section/subsection/value", false); @@ -158,16 +157,17 @@ There are four macros available for this: // Returns the specified editor setting's value, // defaulting to "Untitled" if it doesn't exist. EDITOR_DEF("section/subsection/value", "Untitled"); +``` If a default value has been specified elsewhere, don't specify it again to avoid repetition: -.. code-block:: cpp - +``` // Returns the value of the project setting. GLOBAL_GET("section/subsection/value"); // Returns the value of the editor setting. EDITOR_GET("section/subsection/value"); +``` It's recommended to use `GLOBAL_DEF`/`EDITOR_DEF` only once per setting and use `GLOBAL_GET`/`EDITOR_GET` in all other places where it's referenced. @@ -200,8 +200,7 @@ Note: Also, always try to return processable data so the engine can keep running well. -.. code-block:: cpp - +``` // Conditionally prints an error message and returns from the function. // Use this in methods which don't return a value. ERR_FAIL_COND_MSG(!mesh.is_valid(), vformat("Couldn't load mesh at: %s", path)); @@ -237,7 +236,7 @@ Note: // except for testing crash handling code. Godot's philosophy // is to never crash, both in the editor and in exported projects. CRASH_NOW_MSG("Can't predict the future! Aborting."); - +``` See also: diff --git a/development/cpp/configuring_an_ide/kdevelop.md b/development/cpp/configuring_an_ide/kdevelop.md index 5ed466c..fa83dfa 100644 --- a/development/cpp/configuring_an_ide/kdevelop.md +++ b/development/cpp/configuring_an_ide/kdevelop.md @@ -32,8 +32,7 @@ Importing the project - Under **Language Support** open the **Includes/Imports** tab and add the following paths: - .. code-block:: none - +``` . // A dot, to indicate the root of the Godot project core/ core/os/ @@ -41,6 +40,7 @@ Importing the project drivers/ platform// // Replace with a folder corresponding to your current platform +``` .. figure:: img/kdevelop_addincludes.png) :figclass: figure-w480 diff --git a/development/cpp/configuring_an_ide/xcode.md b/development/cpp/configuring_an_ide/xcode.md index 5388b28..0db37dd 100644 --- a/development/cpp/configuring_an_ide/xcode.md +++ b/development/cpp/configuring_an_ide/xcode.md @@ -81,9 +81,9 @@ To enable debugging support you need to edit the external build target's build a the project directory within the script. - Create a script that will give the binary a name that Xcode can recognize, e.g.: -.. 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 diff --git a/development/cpp/core_types.md b/development/cpp/core_types.md index e4b2416..b1a080f 100644 --- a/development/cpp/core_types.md +++ b/development/cpp/core_types.md @@ -79,24 +79,24 @@ should not be used. Instead, a few other ones are provided. For C-style allocation, Godot provides a few macros: -.. code-block:: none - +``` memalloc() memrealloc() memfree() +``` These are equivalent to the usual malloc, realloc, free of the standard C library. For C++-style allocation, special macros are provided: -.. code-block:: none - +``` memnew( Class / Class(args) ) memdelete( instance ) memnew_arr( Class , amount ) memdelete_arr( pointer to array ) +``` which are equivalent to new, delete, new[] and delete[]. @@ -107,21 +107,21 @@ For dynamic memory, the PoolVector<> template is provided. PoolVector is a standard vector class, and is very similar to vector in the C++ standard library. To create a PoolVector buffer, use this: -.. code-block:: cpp - +``` PoolVector data; +``` PoolVector can be accessed using the [] operator and a few helpers exist for this: -.. code-block:: cpp - +``` PoolVector::Read r = data.read() int someint = r[4] +``` -.. code-block:: cpp - +``` PoolVector::Write w = data.write() w[4] = 22; +``` These operations allow fast read/write from PoolVectors and keep it locked until they go out of scope. However, PoolVectors should be used @@ -149,11 +149,11 @@ in C++ are often inlined and make the binary size much fatter, both in debug symbols and code. List, Set and Map can be iterated using pointers, like this: -.. code-block:: cpp - +``` for(List::Element *E=somelist.front();E;E=E->next()) { print_line(E->get()); // print the element } +``` The Vector<> class also has a few nice features: diff --git a/development/cpp/custom_audiostreams.md b/development/cpp/custom_audiostreams.md index f0001c0..d617c7d 100644 --- a/development/cpp/custom_audiostreams.md +++ b/development/cpp/custom_audiostreams.md @@ -45,8 +45,7 @@ ResourceLoader. ResourceLoader loads once and references the same object regardless how many times `load` is called on a specific resource. Therefore, playback state must be self-contained in AudioStreamPlayback. -.. code-block:: cpp - +``` /* audiostream_mytone.h */ #include "core/reference.h" @@ -75,9 +74,9 @@ Therefore, playback state must be self-contained in AudioStreamPlayback. protected: static void _bind_methods(); }; +``` -.. code-block:: cpp - +``` /* audiostream_mytone.cpp */ #include "audiostream_mytone.h" @@ -112,6 +111,7 @@ Therefore, playback state must be self-contained in AudioStreamPlayback. ClassDB::bind_method(D_METHOD("reset"), &AudioStreamMyTone::reset); ClassDB::bind_method(D_METHOD("get_stream_name"), &AudioStreamMyTone::get_stream_name); } +``` References: ~~~~~~~~~~~ @@ -126,8 +126,7 @@ AudioStreamPlayer uses `mix` callback to obtain PCM data. The callback must matc Since AudioStreamPlayback is controlled by the audio thread, i/o and dynamic memory allocation are forbidden. -.. code-block:: cpp - +``` /* audiostreamplayer_mytone.h */ #include "core/reference.h" @@ -163,9 +162,9 @@ Since AudioStreamPlayback is controlled by the audio thread, i/o and dynamic mem AudioStreamPlaybackMyTone(); ~AudioStreamPlaybackMyTone(); }; +``` -.. code-block:: cpp - +``` /* audiostreamplayer_mytone.cpp */ #include "audiostreamplayer_mytone.h" @@ -227,6 +226,7 @@ Since AudioStreamPlayback is controlled by the audio thread, i/o and dynamic mem bool AudioStreamPlaybackMyTone::is_playing() const { return active; } +``` Resampling ~~~~~~~~~~ @@ -238,8 +238,7 @@ Godot provides cubic interpolation for audio resampling. Instead of overloading `mix`, AudioStreamPlaybackResampled uses `mix_internal` to query AudioFrames and `get_stream_sampling_rate` to query current mix rate. -.. code-block:: cpp - +``` #include "core/reference.h" #include "core/resource.h" #include "servers/audio/audio_stream.h" @@ -279,8 +278,7 @@ query AudioFrames and `get_stream_sampling_rate` to query current mix rate. ~AudioStreamPlaybackResampledMyTone(); }; -.. code-block:: cpp - +``` #include "mytone_audiostream_resampled.h" #include "core/math/math_funcs.h" @@ -343,6 +341,7 @@ query AudioFrames and `get_stream_sampling_rate` to query current mix rate. bool AudioStreamPlaybackResampledMyTone::is_playing() const { return active; } +``` References: ~~~~~~~~~~~ diff --git a/development/cpp/custom_godot_servers.md b/development/cpp/custom_godot_servers.md index 0bee915..510098d 100644 --- a/development/cpp/custom_godot_servers.md +++ b/development/cpp/custom_godot_servers.md @@ -38,8 +38,7 @@ Creating a Godot server At minimum, a server must have a static instance, a sleep timer, a thread loop, an initialization state and a cleanup procedure. -.. code-block:: cpp - +``` #ifndef HILBERT_HOTEL_H #define HILBERT_HOTEL_H @@ -91,9 +90,9 @@ an initialization state and a cleanup procedure. }; #endif +``` -.. code-block:: cpp - +``` #include "hilbert_hotel.h" #include "core/dictionary.h" @@ -235,9 +234,9 @@ an initialization state and a cleanup procedure. HilbertHotel::HilbertHotel() { singleton = this; } +``` -.. code-block:: cpp - +``` /* prime_225.h */ #include "core/int_types.h" @@ -269,6 +268,7 @@ an initialization state and a cleanup procedure. 1283,1289,1291,1297,1301,1303,1307,1319,1321, 1327,1361,1367,1373,1381,1399,1409,1423,1427 }; +``` Custom managed resource data ---------------------------- @@ -278,8 +278,7 @@ Godot servers implement a mediator pattern. All data types inherit `RID_Data`. RID_Owner maintains a list of RIDs. In practice, RIDs are similar to writing object-oriented C code. -.. code-block:: cpp - +``` class InfiniteBus : public RID_Data { RID self; @@ -311,6 +310,7 @@ object-oriented C code. InfiniteBus(uint64_t prime) : prime_num(prime), num(1) {}; ~InfiniteBus() {}; } +``` References ~~~~~~~~~~~ @@ -332,8 +332,7 @@ class must be created to reference the proper Godot server. In `register_server_types()`, `Engine::get_singleton()->add_singleton` is used to register the dummy class in GDScript. -.. code-block:: cpp - +``` /* register_types.cpp */ #include "register_types.h" @@ -364,14 +363,15 @@ is used to register the dummy class in GDScript. memdelete(_hilbert_hotel); } } +``` -.. code-block:: cpp - +``` /* register_types.h */ /* Yes, the word in the middle must be the same as the module folder name */ void register_hilbert_hotel_types(); void unregister_hilbert_hotel_types(); +``` - `servers/register_server_types.cpp ( https://github.com/godotengine/godot/blob/master/servers/register_server_types.cpp )` @@ -380,24 +380,23 @@ Bind methods The dummy class binds singleton methods to GDScript. In most cases, the dummy class methods wraps around. -.. code-block:: cpp - +``` Variant _HilbertHotel::get_bus_info(RID id) { return HilbertHotel::get_singleton()->get_bus_info(id); } +``` Binding Signals It is possible to emit signals to GDScript by calling the GDScript dummy object. -.. code-block:: cpp - +``` void HilbertHotel::_emit_occupy_room(uint64_t room, RID rid) { _HilbertHotel::get_singleton()->_occupy_room(room, rid); } +``` -.. code-block:: cpp - +``` class _HilbertHotel : public Object { GDCLASS(_HilbertHotel, Object); @@ -422,9 +421,9 @@ It is possible to emit signals to GDScript by calling the GDScript dummy object. }; #endif +``` -.. code-block:: cpp - +``` _HilbertHotel *_HilbertHotel::singleton = NULL; _HilbertHotel *_HilbertHotel::get_singleton() { return singleton; } @@ -461,6 +460,7 @@ It is possible to emit signals to GDScript by calling the GDScript dummy object. _HilbertHotel::~_HilbertHotel() { } +``` MessageQueue ------------ @@ -481,8 +481,7 @@ Summing it up Here is the GDScript sample code: -:: - +``` extends Node func _ready(): @@ -501,6 +500,7 @@ Here is the GDScript sample code: func _print_occupy_room(room_number, r_id): print("Room number: " + str(room_number) + ", RID: " + str(r_id)) print(HilbertHotel.get_bus_info(r_id)) +``` Notes ~~~~~ diff --git a/development/cpp/custom_modules_in_cpp.md b/development/cpp/custom_modules_in_cpp.md index faff525..1d545a6 100644 --- a/development/cpp/custom_modules_in_cpp.md +++ b/development/cpp/custom_modules_in_cpp.md @@ -44,8 +44,7 @@ a different VCS into modules and use it. The example module will be called "summator" (`godot/modules/summator`). Inside we will create a simple summator class: -.. code-block:: cpp - +``` /* summator.h */ #ifndef SUMMATOR_H @@ -70,11 +69,11 @@ Inside we will create a simple summator class: }; #endif // SUMMATOR_H +``` And then the cpp file. -.. code-block:: cpp - +``` /* summator.cpp */ #include "summator.h" @@ -104,27 +103,26 @@ And then the cpp file. Then, the new class needs to be registered somehow, so two more files need to be created: -.. code-block:: none - +``` register_types.h register_types.cpp +``` -.. important:: +.. important: These files must be in the top-level folder of your module (next to your `SCsub` and `config.py` files) for the module to be registered properly. These files should contain the following: -.. code-block:: cpp - +``` /* register_types.h */ void register_summator_types(); void unregister_summator_types(); /* yes, the word in the middle must be the same as the module folder name */ +``` -.. code-block:: cpp - +``` /* register_types.cpp */ #include "register_types.h" @@ -139,25 +137,26 @@ These files should contain the following: void unregister_summator_types() { // Nothing to do here in this example. } +``` Next, we need to create a `SCsub` file so the build system compiles this module: -.. code-block:: python - +``` # SCsub Import('env') env.add_source_files(env.modules_sources, "*.cpp") # Add all cpp files to the build +``` With multiple sources, you can also add each file individually to a Python string list: -.. code-block:: python - +``` src_list = ["summator.cpp", "other.cpp", "etc.cpp"] env.add_source_files(env.modules_sources, src_list) +``` This allows for powerful possibilities using Python to construct the file list using loops and logic statements. Look at some modules that ship with Godot by @@ -166,17 +165,16 @@ default for examples. To add include directories for the compiler to look at you can append it to the environment's paths: -.. code-block:: python - +``` env.Append(CPPPATH=["mylib/include"]) # this is a relative path env.Append(CPPPATH=["#myotherlib/include"]) # this is an 'absolute' path +``` If you want to add custom compiler flags when building your module, you need to clone `env` first, so it won't add those flags to whole Godot build (which can cause errors). Example `SCsub` with custom flags: -.. code-block:: python - +``` # SCsub Import('env') @@ -188,12 +186,12 @@ Example `SCsub` with custom flags: # If you need to, you can: # - Append CFLAGS for C code only. # - Append CXXFLAGS for C++ code only. +``` And finally, the configuration file for the module, this is a simple python script that must be named `config.py`: -.. code-block:: python - +``` # config.py def can_build(env, platform): @@ -201,6 +199,7 @@ python script that must be named `config.py`: def configure(env): pass +``` The module is asked if it's OK to build for the specific platform (in this case, `True` means it will build for every platform). @@ -208,14 +207,14 @@ this case, `True` means it will build for every platform). And that's it. Hope it was not too complex! Your module should look like this: -.. code-block:: none - +``` godot/modules/summator/config.py godot/modules/summator/summator.h godot/modules/summator/summator.cpp godot/modules/summator/register_types.h godot/modules/summator/register_types.cpp godot/modules/summator/SCsub +``` You can then zip it and share the module with everyone else. When building for every platform (instructions in the previous sections), @@ -281,18 +280,18 @@ practical thing to do: 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. @@ -333,8 +332,7 @@ changed, finding such files and eventually linking the final binary takes a long The solution to avoid such a cost is to build our own module as a shared library that will be dynamically loaded when starting our game's binary. -.. code-block:: python - +``` # SCsub Import('env') @@ -370,16 +368,17 @@ library that will be dynamically loaded when starting our game's binary. # (e.g. ".x11.tools.64") but without the final ".so". shared_lib_shim = shared_lib[0].name.rsplit('.', 1)[0] env.Append(LIBS=[shared_lib_shim]) +``` Once compiled, we should end up with a `bin` directory containing both the `godot*` binary and our `libsummator*.so`. However given the .so is not in a standard directory (like `/usr/lib`), we have to help our binary find it during runtime with the `LD_LIBRARY_PATH` environment variable: -.. code-block:: shell - +``` export LD_LIBRARY_PATH="$PWD/bin/" ./bin/godot* +``` Note: @@ -391,8 +390,7 @@ module as shared library (for development) or as a part of the Godot binary (for release). To do that we can define a custom flag to be passed to SCons using the `ARGUMENT` command: -.. code-block:: python - +``` # SCsub Import('env') @@ -416,6 +414,7 @@ using the `ARGUMENT` command: else: # Static compilation module_env.add_source_files(env.modules_sources, sources) +``` Now by default `scons` command will build our module as part of Godot's binary and as a shared library when passing `summator_shared=yes`. @@ -423,9 +422,9 @@ and as a shared library when passing `summator_shared=yes`. Finally, you can even speed up the build further by explicitly specifying your shared module as target in the SCons command: -.. code-block:: shell - +``` scons summator_shared=yes platform=x11 bin/libsummator.x11.tools.64.so +``` Writing custom documentation ---------------------------- @@ -443,8 +442,7 @@ There are several steps in order to setup custom docs for the module: 2. Now, we need to edit `config.py`, add the following snippet: - .. code-block:: python - +``` def get_doc_path(): return "doc_classes" @@ -452,6 +450,7 @@ There are several steps in order to setup custom docs for the module: return [ "Summator", ] +``` 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 @@ -468,12 +467,15 @@ Tip: You can use Git to check if you have missed some of your classes by checking the - untracked files with `git status`. For example:: + untracked files with `git status`. For example: +``` user@host:~/godot$ git status +``` - Example output:: + Example output: +``` Untracked files: (use "git add ..." to include in what will be committed) @@ -482,7 +484,7 @@ Tip: doc/classes/MyClass5D.xml doc/classes/MyClass6D.xml ... - +``` 3. Now we can generate the documentation: @@ -494,9 +496,9 @@ to an another folder, and just copy over the files that you need. Run command: - :: - +``` user@host:~/godot/bin$ ./bin/ --doctool . +``` Now if you go to the `godot/modules/summator/doc_classes` folder, you will see that it contains a `Summator.xml` file, or any other classes, that you referenced @@ -518,11 +520,10 @@ on top of the newer ones. Note that if you don't have write access rights to your supplied ` *r_extensions) const; }; #endif // RESOURCE_SAVER_JSON_H +``` -.. code-block:: cpp - +``` /* resource_saver_json.cpp */ #include "resource_saver_json.h" @@ -153,6 +152,7 @@ If you'd like to be able to edit and save a resource, you can implement a r_extensions->push_back("json"); } } +``` Creating custom data types -------------------------- @@ -163,8 +163,7 @@ understand additional binary formats such as machine learning models. Here is an example of creating a custom datatype: -.. code-block:: cpp - +``` /* resource_json.h */ #ifndef RESOURCE_JSON_H @@ -195,9 +194,9 @@ Here is an example of creating a custom datatype: Dictionary get_dict(); }; #endif // RESOURCE_JSON_H +``` -.. code-block:: cpp - +``` /* resource_json.cpp */ #include "resource_json.h" @@ -257,6 +256,7 @@ Here is an example of creating a custom datatype: Dictionary JsonResource::get_dict() { return content; } +``` Considerations ~~~~~~~~~~~~~~ @@ -267,8 +267,7 @@ Therefore, Godot call translations are required. For example, here is the code for translating `FileAccess` calls into `std::istream`. -.. code-block:: cpp - +``` #include "core/os/file_access.h" #include @@ -297,7 +296,7 @@ calls into `std::istream`. private: FileAccess *_file; }; - +``` References ~~~~~~~~~~ @@ -313,15 +312,14 @@ Godot registers `ResourcesFormatLoader` with a `ResourceLoader` handler. The handler selects the proper loader automatically when `load` is called. -.. code-block:: cpp - +``` /* register_types.h */ void register_json_types(); void unregister_json_types(); +``` -.. code-block:: cpp - +``` /* register_types.cpp */ #include "register_types.h" @@ -351,6 +349,7 @@ when `load` is called. ResourceSaver::remove_resource_format_saver(json_saver); json_saver.unref(); } +``` References ~~~~~~~~~~ @@ -363,8 +362,7 @@ Loading it on GDScript Save a file called `demo.json` with the following contents and place it in the project's root folder: -.. code-block:: json - +``` { "savefilename": "demo.json", "demo": [ @@ -375,12 +373,15 @@ project's root folder: "loaders" ] } +``` Then attach the following script to any node:: +``` extends Node onready var json_resource = load("res://demo.json") func _ready(): print(json_resource.get_dict()) +``` \ No newline at end of file diff --git a/development/cpp/introduction_to_godot_development.md b/development/cpp/introduction_to_godot_development.md index 349a3b6..93fbb3f 100644 --- a/development/cpp/introduction_to_godot_development.md +++ b/development/cpp/introduction_to_godot_development.md @@ -26,15 +26,15 @@ project. To launch a project directly, you need to run the editor by passing the `-e` argument to Godot Engine's binary from within your project's folder. Typically: -.. code-block:: none - +``` $ cd ~/myproject $ gdb godot > run -e +``` Or: -.. code-block:: none - +``` $ gdb godot > run -e --path ~/myproject +``` diff --git a/development/cpp/macos_debug.md b/development/cpp/macos_debug.md index d604966..02c6ac4 100644 --- a/development/cpp/macos_debug.md +++ b/development/cpp/macos_debug.md @@ -9,8 +9,7 @@ If you want to debug an official build of the editor it should be re-signed with Create an `editor.entitlements` text file with the following contents: -.. code-block:: xml - +``` @@ -31,10 +30,13 @@ Create an `editor.entitlements` text file with the following contents: +``` -Then use the following command to re-sign the editor:: +Then use the following command to re-sign the editor: +``` codesign -s - --deep --force --options=runtime --entitlements ./editor.entitlements ./path/to/Godot.app +``` Debugging exported project -------------------------- diff --git a/development/cpp/object_class.md b/development/cpp/object_class.md index 2c31182..a5e3866 100644 --- a/development/cpp/object_class.md +++ b/development/cpp/object_class.md @@ -17,21 +17,21 @@ inherit directly or indirectly from it. Objects provide reflection and editable properties, and declaring them is a matter of using a single macro like this. -.. code-block:: cpp - +``` class CustomObject : public Object { GDCLASS(CustomObject, Object); // this is required to inherit }; +``` This makes Objects gain a lot of functionality, like for example -.. code-block:: cpp - +``` obj = memnew(CustomObject); print_line("Object class: ", obj->get_class()); // print object class obj2 = Object::cast_to(obj); // converting between classes, this also works without RTTI enabled. +``` References: ~~~~~~~~~~~ @@ -47,18 +47,18 @@ their methods properties and integer constants. Classes are registered by calling: -.. code-block:: cpp - +``` ClassDB::register_class() +``` Registering it will allow the class to be instanced by scripts, code, or creating them again when deserializing. Registering as virtual is the same but it can't be instanced. -.. code-block:: cpp - +``` ClassDB::register_virtual_class() +``` Object-derived classes can override the static function `static void _bind_methods()`. When one class is registered, this @@ -70,15 +70,15 @@ virtual automatically. Inside `bind_methods`, there are a couple of things that can be done. Registering functions is one: -.. code-block:: cpp - +``` ClassDB::bind_method(D_METHOD("methodname", "arg1name", "arg2name"), &MyCustomMethod); +``` Default values for arguments can be passed in reverse order: -.. code-block:: cpp - +``` ClassDB::bind_method(D_METHOD("methodname", "arg1name", "arg2name"), &MyCustomType::method, DEFVAL(-1)); // default value for arg2name +``` `D_METHOD` is a macro that converts "methodname" to a StringName for more efficiency. Argument names are used for introspection, but when @@ -101,26 +101,26 @@ Constants Classes often have enums such as: -.. code-block:: cpp - +``` enum SomeMode { MODE_FIRST, MODE_SECOND }; +``` For these to work when binding to methods, the enum must be declared convertible to int, for this a macro is provided: -.. code-block:: cpp - +``` VARIANT_ENUM_CAST(MyClass::SomeMode); // now functions that take SomeMode can be bound. +``` The constants can also be bound inside `bind_methods`, by using: -.. code-block:: cpp - +``` BIND_CONSTANT(MODE_FIRST); BIND_CONSTANT(MODE_SECOND); +``` Properties (set/get) -------------------- @@ -133,15 +133,15 @@ Objects export properties, properties are useful for the following: Properties are usually defined by the PropertyInfo() class. Usually constructed as: -.. code-block:: cpp - +``` PropertyInfo(type, name, hint, hint_string, usage_flags) +``` For example: -.. code-block:: cpp - +``` PropertyInfo(Variant::INT, "amount", PROPERTY_HINT_RANGE, "0,49,1", PROPERTY_USAGE_EDITOR) +``` This is an integer property, named "amount", hint is a range, range goes from 0 to 49 in steps of 1 (integers). It is only usable for the editor @@ -149,9 +149,9 @@ from 0 to 49 in steps of 1 (integers). It is only usable for the editor Another example: -.. code-block:: cpp - +``` PropertyInfo(Variant::STRING, "modes", PROPERTY_HINT_ENUM, "Enabled,Disabled,Turbo") +``` This is a string property, can take any string but the editor will only allow the defined hint ones. Since no usage flags were specified, the @@ -169,9 +169,9 @@ impossible unless using operator []. From `bind_methods()`, properties can be created and bound as long as set/get functions exist. Example: -.. code-block:: cpp - +``` ADD_PROPERTY(PropertyInfo(Variant::INT, "amount"), "set_amount", "get_amount") +``` This creates the property using the setter and the getter. @@ -188,12 +188,12 @@ they are NOT virtual, DO NOT make them virtual, they are called for every override and the previous ones are not invalidated (multilevel call). -.. code-block:: cpp - +``` protected: void _get_property_list(List *r_props) const; // return list of properties bool _get(const StringName &p_property, Variant &r_value) const; // return true if property was found bool _set(const StringName &p_property, const Variant &p_value); // return true if property was found +``` This is also a little less efficient since `p_property` must be compared against the desired names in serial order. @@ -204,12 +204,12 @@ Dynamic casting Godot provides dynamic casting between Object-derived classes, for example: -.. code-block:: cpp - +``` void somefunc(Object *some_obj) { Button *button = Object::cast_to