diff --git a/contributing/development/best_practices_for_engine_contributors.rst b/contributing/development/best_practices_for_engine_contributors.rst index 87fdf14a000..b0dd1de5608 100644 --- a/contributing/development/best_practices_for_engine_contributors.rst +++ b/contributing/development/best_practices_for_engine_contributors.rst @@ -167,7 +167,7 @@ who design software) to actually understand all future user needs. Trying to write very flexible structures that cater to many use cases at once is often a mistake. -We may come up with something we believe is brilliant but later find out that +We may come up with something we believe is brilliant, but later find out that users will never even use half of it or that they require features that don't quite fit into our original design, forcing us to either throw it away or make it even more complex. diff --git a/contributing/development/code_style_guidelines.rst b/contributing/development/code_style_guidelines.rst index 2b6e681a6c3..0d4fbd5defe 100644 --- a/contributing/development/code_style_guidelines.rst +++ b/contributing/development/code_style_guidelines.rst @@ -35,7 +35,7 @@ fine. If you plan to contribute regularly, however, we strongly advise that you set up clang-format locally to check and automatically fix all your commits. .. warning:: Godot's code style should *not* be applied to third-party code, - i.e. that is included in Godot's source tree but was not written + i.e. code that is included in Godot's source tree, but was not written specifically for our project. Such code usually comes from different upstream projects with their own style guides (or lack thereof), and don't want to introduce differences that would make @@ -65,7 +65,7 @@ Pre-commit hook ^^^^^^^^^^^^^^^ For ease of use, we provide hooks for Git with the `pre-commit `__ -Python framework that will run clang-format automatically on all your commits with the +Python framework that will run clang-format automatically on all your commits with the correct version of clang-format. To set up: @@ -77,7 +77,7 @@ To set up: You can also run the hook manually with ``pre-commit run``. -.. note:: +.. note:: Previously, we supplied a hook in the folder ``misc/hooks``. If you copied the script manually, these hooks should still work, but symlinks will be broken. @@ -382,7 +382,7 @@ instead. // ... } -For member variables, don't use Javadoc-style comments but use single-line comments instead: +For member variables, don't use Javadoc-style comments, but use single-line comments instead: .. code-block:: cpp diff --git a/contributing/development/compiling/introduction_to_the_buildsystem.rst b/contributing/development/compiling/introduction_to_the_buildsystem.rst index e19ed0ba4c3..e7ff838c749 100644 --- a/contributing/development/compiling/introduction_to_the_buildsystem.rst +++ b/contributing/development/compiling/introduction_to_the_buildsystem.rst @@ -403,7 +403,7 @@ To perform an SCU build, use the ``scu_build=yes`` SCons option. regular build prior to submitting the PR. This is because SCU builds by nature include headers from earlier ``.cpp`` files in the translation unit, therefore won't catch all the includes you will - need in a regular build. The CI will catch these errors but it will + need in a regular build. The CI will catch these errors, but it will usually be faster to catch them on a local build on your machine. Export templates diff --git a/contributing/documentation/building_the_manual.rst b/contributing/documentation/building_the_manual.rst index 4ac1d5059b4..749cdb12b64 100644 --- a/contributing/documentation/building_the_manual.rst +++ b/contributing/documentation/building_the_manual.rst @@ -120,7 +120,7 @@ If you run into errors, you may try the following command: If you get a ``MemoryError`` or ``EOFError``, you can remove the ``classes/`` folder and run ``make`` again. -This will drop the class references from the final HTML documentation but will keep the +This will drop the class references from the final HTML documentation, but will keep the rest intact. .. important:: diff --git a/contributing/documentation/contributing_to_the_documentation.rst b/contributing/documentation/contributing_to_the_documentation.rst index 396276fa56d..a6abad0d295 100644 --- a/contributing/documentation/contributing_to_the_documentation.rst +++ b/contributing/documentation/contributing_to_the_documentation.rst @@ -89,7 +89,7 @@ and to log in to use it. Once logged in, you can propose change like so: 4. At the bottom of the web page, summarize the changes you made and click the button **Propose file change**. Make sure to replace the placeholder "Update file.rst" - by a short but clear one-line description, as this is the commit title. + by a short, but clear one-line description, as this is the commit title. 5. On the following screens, click the **Create pull request** button until you see a message like *Username wants to merge 1 commit into godotengine:master diff --git a/contributing/workflow/pr_review_guidelines.rst b/contributing/workflow/pr_review_guidelines.rst index b0cfc136949..66281dcc1a9 100644 --- a/contributing/workflow/pr_review_guidelines.rst +++ b/contributing/workflow/pr_review_guidelines.rst @@ -12,7 +12,7 @@ Pull request review process wanting to know how to ensure that their PR is merged. From a high level, the ideal life cycle of a pull request looks like the -following: +following: 1. A contributor opens a PR that fixes a specific problem (optimally closing a GitHub `issue `_ or implementing @@ -33,9 +33,9 @@ following: This document will explain steps 2, 3, 4, and 5 in more detail. For a more detailed explanation of the pull request workflow please see the :ref:`pull -request workflow document `. +request workflow document `. -.. note:: +.. note:: In practice these steps may blend together. Oftentimes maintainers will provide comments on code style and code quality at the same time and will approve a pull request for both. @@ -160,7 +160,7 @@ As you review pull requests, keep the Godot `Code of Conduct * Always assume positive intent from others. -* Feedback is always welcome but keep your criticism constructive. +* Feedback is always welcome, but keep your criticism constructive. Here are some things to avoid as you iterate on a pull request with a contributor: @@ -178,7 +178,7 @@ contributor: areas and in performance-sensitive areas than it is in editor code for example. -* **Expanding the scope of a pull request.** +* **Expanding the scope of a pull request.** Providing context or related/similar issues or proposals that may be fixed similarly can be helpful, but adding a "may as well fix that thing over there @@ -253,7 +253,7 @@ Merging pull requests In general, pull requests should only be merged by members of the production team or team leaders for pull requests in their area of the engine. For example, the networking team leader could merge a networking pull request that doesn't -substantially change non-networking sections of code. +substantially change non-networking sections of code. In practice it is best to wait for a member of the production team to merge the pull request as they keep a close eye on the entire codebase and will likely @@ -275,7 +275,7 @@ steps yourself. Production team members should ensure that the right people look at a pull request before it is merged. In some cases this may require multiple people to weigh in. In other cases, only one substantive approval is needed before the -code can be merged. +code can be merged. In general, try not to merge things based on one review alone, especially if it is your own. Get a second opinion from another maintainer, and make sure all the diff --git a/tutorials/2d/2d_sprite_animation.rst b/tutorials/2d/2d_sprite_animation.rst index bce8da40dd3..912cbffbfec 100644 --- a/tutorials/2d/2d_sprite_animation.rst +++ b/tutorials/2d/2d_sprite_animation.rst @@ -271,7 +271,7 @@ released. it's important to keep in mind that ``play()`` isn't applied instantly. Instead, it's applied the next time the :ref:`AnimationPlayer ` is processed. This may end up being on the next frame, causing a 'glitch' frame, - where the property change was applied but the animation was not. + where the property change was applied, but the animation was not. If this turns out to be a problem, after calling ``play()``, you can call ``advance(0)`` to update the animation immediately. diff --git a/tutorials/2d/2d_transforms.rst b/tutorials/2d/2d_transforms.rst index 8403913f157..b8e8ccee8cd 100644 --- a/tutorials/2d/2d_transforms.rst +++ b/tutorials/2d/2d_transforms.rst @@ -45,7 +45,7 @@ resizing or stretching the screen. This transform is used internally (as described in :ref:`doc_multiple_resolutions`), but can also be manually set on each viewport. -Input events are multiplied by this transform but lack the ones above. To +Input events are multiplied by this transform, but lack the ones above. To convert InputEvent coordinates to local CanvasItem coordinates, the :ref:`CanvasItem.make_input_local() ` function was added for convenience. diff --git a/tutorials/3d/environment_and_post_processing.rst b/tutorials/3d/environment_and_post_processing.rst index ff84da5226f..cacc178e0b8 100644 --- a/tutorials/3d/environment_and_post_processing.rst +++ b/tutorials/3d/environment_and_post_processing.rst @@ -499,7 +499,7 @@ own, the effect may not be that noticeable, which is intended. Instead, :abbr:`SSIL (Screen-Space Indirect Lighting)` is meant to be used as a *complement* to other global illumination techniques such as VoxelGI, SDFGI and LightmapGI. :abbr:`SSIL (Screen-Space Indirect Lighting)` also provides -a subtle ambient occlusion effect, similar to SSAO but with less detail. +a subtle ambient occlusion effect, similar to SSAO, but with less detail. This feature only provides indirect lighting. It is not a full global illumination solution. This makes it different from screen-space global illumination (SSGI) diff --git a/tutorials/3d/lights_and_shadows.rst b/tutorials/3d/lights_and_shadows.rst index 6f3b31b2add..f2806896a0c 100644 --- a/tutorials/3d/lights_and_shadows.rst +++ b/tutorials/3d/lights_and_shadows.rst @@ -160,12 +160,12 @@ at the cost of decreased performance. all" settings. To achieve the best visuals, you may need to use different shadow bias values on a per-light basis. -**Note on Appearance Changes**: When enabling shadows on a light, be aware that the light's -appearance might change compared to when it's rendered without shadows in the compatibility -renderer. Due to limitations with older mobile devices, shadows are implemented using a multi-pass -rendering approach so lights with shadows are rendered in sRGB space instead of linear space. -This change in rendering space can sometimes drastically alter the light's appearance. To achieve a similar -appearance to an unshadowed light, you may need to adjust the light's energy setting. +**Note on Appearance Changes**: When enabling shadows on a light, be aware that the light's +appearance might change compared to when it's rendered without shadows in the compatibility +renderer. Due to limitations with older mobile devices, shadows are implemented using a multi-pass +rendering approach so lights with shadows are rendered in sRGB space instead of linear space. +This change in rendering space can sometimes drastically alter the light's appearance. To achieve a similar +appearance to an unshadowed light, you may need to adjust the light's energy setting. Directional light ----------------- @@ -208,10 +208,10 @@ receive low-resolution shadows that may appear blocky. To fix this, a technique named *Parallel Split Shadow Maps* (PSSM) is used. This splits the view frustum in 2 or 4 areas. Each area gets its own shadow map. This allows small areas close to the viewer to have the same shadow resolution -as a huge, far-away area. When shadows are enabled for DirectionalLight3D, the -default shadow mode is PSSM with 4 splits. In scenarios where an object is large -enough to appear in all four splits, it results in increased draw calls. Specifically, -such an object will be rendered five times in total: once for each of the four shadow +as a huge, far-away area. When shadows are enabled for DirectionalLight3D, the +default shadow mode is PSSM with 4 splits. In scenarios where an object is large +enough to appear in all four splits, it results in increased draw calls. Specifically, +such an object will be rendered five times in total: once for each of the four shadow splits and once for the final scene rendering. This can impact performance, understanding this behavior is important for optimizing your scene and managing performance expectations. @@ -535,7 +535,7 @@ not use mipmaps, which makes them faster to render. However, projectors will look grainy at distance. **Nearest/Linear Mipmaps** will look smoother at a distance, but projectors will look blurry when viewed from oblique angles. This can be resolved by using **Nearest/Linear Mipmaps Anisotropic**, which is the -highest-quality mode but also the most expensive. +highest-quality mode, but also the most expensive. If your project has a pixel art style, consider setting the filter to one of the **Nearest** values so that projectors use nearest-neighbor filtering. Otherwise, diff --git a/tutorials/3d/mesh_lod.rst b/tutorials/3d/mesh_lod.rst index d073dbffd3e..5f0e7623ed4 100644 --- a/tutorials/3d/mesh_lod.rst +++ b/tutorials/3d/mesh_lod.rst @@ -148,14 +148,14 @@ independently from other viewports. The default mesh LOD threshold of 1 pixel is tuned to look *perceptually* lossless; it provides a significant performance gain with an unnoticeable loss in quality. Higher values will make LOD transitions happen sooner when the -camera moves away, resulting in higher performance but lower quality. +camera moves away, resulting in higher performance, but lower quality. If you need to perform per-object adjustments to mesh LOD, you can adjust how aggressive LOD transitions should be by adjusting the **LOD Bias** property on any node that inherits from GeometryInstance3D. Values *above* ``1.0`` will make -LOD transitions happen later than usual (resulting in higher quality but lower +LOD transitions happen later than usual (resulting in higher quality, but lower performance). Values *below* ``1.0`` will make LOD transitions happen sooner than -usual (resulting in lower quality but higher performance). +usual (resulting in lower quality, but higher performance). Additionally, ReflectionProbe nodes have their own **Mesh LOD Threshold** property that can be adjusted to improve rendering performance when the reflection probe diff --git a/tutorials/3d/using_decals.rst b/tutorials/3d/using_decals.rst index 9998865d5a5..8c42d525b45 100644 --- a/tutorials/3d/using_decals.rst +++ b/tutorials/3d/using_decals.rst @@ -240,7 +240,7 @@ textures should be filtered. **Nearest/Linear** does not use mipmaps. However, decals will look grainy at a distance. **Nearest/Linear Mipmaps** will look smoother at a distance, but decals will look blurry when viewed from oblique angles. This can be resolved by using **Nearest/Linear Mipmaps Anisotropic**, -which provides the highest quality but is also slower to render. +which provides the highest quality, but is also slower to render. If your project has a pixel art style, consider setting the filter to one of the **Nearest** values so that decals use nearest-neighbor filtering. Otherwise, diff --git a/tutorials/3d/variable_rate_shading.rst b/tutorials/3d/variable_rate_shading.rst index 82f20fae7cd..81b902c25cf 100644 --- a/tutorials/3d/variable_rate_shading.rst +++ b/tutorials/3d/variable_rate_shading.rst @@ -37,12 +37,12 @@ density map linked at the bottom of this page: .. figure:: img/variable_rate_shading_textured_enabled.webp :align: center - :alt: Variable rate shading enabled in textured scene (lower quality but higher performance) + :alt: Variable rate shading enabled in textured scene (lower quality, but higher performance) - Variable rate shading enabled in textured scene (lower quality but higher performance) + Variable rate shading enabled in textured scene (lower quality, but higher performance) When used in scenes with low-frequency detail (such as scenes with a -stylized/low-poly aesthetic), it's possible to achieve similar performance gains +stylized/low-poly aesthetic), it's possible to achieve similar performance gains, but with less reduction in visual quality: .. figure:: img/variable_rate_shading_untextured_disabled.webp @@ -53,9 +53,9 @@ but with less reduction in visual quality: .. figure:: img/variable_rate_shading_untextured_enabled.webp :align: center - :alt: Variable rate shading enabled in untextured scene (lower quality but higher performance) + :alt: Variable rate shading enabled in untextured scene (lower quality, but higher performance) - Variable rate shading enabled in untextured scene (lower quality but higher performance) + Variable rate shading enabled in untextured scene (lower quality, but higher performance) Hardware support ---------------- diff --git a/tutorials/3d/visibility_ranges.rst b/tutorials/3d/visibility_ranges.rst index 02cba970372..0c882bd1adf 100644 --- a/tutorials/3d/visibility_ranges.rst +++ b/tutorials/3d/visibility_ranges.rst @@ -15,7 +15,7 @@ On this page, you'll learn: .. seealso:: - If you only need meshes to become less detailed over distance but don't have + If you only need meshes to become less detailed over distance, but don't have manually authored LOD meshes, consider relying on automatic :ref:`doc_mesh_lod` instead. diff --git a/tutorials/3d/volumetric_fog.rst b/tutorials/3d/volumetric_fog.rst index f5fca792360..e32acee8344 100644 --- a/tutorials/3d/volumetric_fog.rst +++ b/tutorials/3d/volumetric_fog.rst @@ -142,11 +142,11 @@ and quality: for better performance. - **Rendering > Environment > Volumetric Fog > Volume Depth:** Number of slices to use along the depth of the froxel buffer for volumetric fog. A lower number - will be more efficient but may result in artifacts appearing during camera + will be more efficient, but may result in artifacts appearing during camera movement. - **Rendering > Environment > Volumetric Fog > Use Filter:** Enables filtering of the volumetric fog effect prior to integration. This substantially blurs - the fog which reduces fine details but also smooths out harsh edges and + the fog which reduces fine details, but also smooths out harsh edges and aliasing artifacts. Disable when more detail is required. .. note:: @@ -159,7 +159,7 @@ Using fog volumes for local volumetric fog ------------------------------------------ Sometimes, you want fog to be constrained to specific areas. Conversely, you may -want to have global volumetric fog but fog should be excluded from certain +want to have global volumetric fog, but fog should be excluded from certain areas. Both approaches can be followed using FogVolume nodes. Here's a quick start guide to using FogVolumes: diff --git a/tutorials/troubleshooting.rst b/tutorials/troubleshooting.rst index 80419494635..23faaab8808 100644 --- a/tutorials/troubleshooting.rst +++ b/tutorials/troubleshooting.rst @@ -25,11 +25,11 @@ There are several ways to improve performance and battery life: which can be up to 4 times faster. - Open the Editor Settings and increase the value of **Low Processor Mode Sleep (µsec)** to ``33000`` (30 FPS). This value determines the amount of *microseconds* - between frames to render. Higher values will make the editor feel less reactive + between frames to render. Higher values will make the editor feel less reactive, but will help decrease CPU and GPU usage significantly. - If you have a node that causes the editor to redraw continuously (such as particles), hide it and show it using a script in the ``_ready()`` method. - This way, it will be hidden in the editor but will still be visible in the + This way, it will be hidden in the editor, but will still be visible in the running project. The editor stutters and flickers on my variable refresh rate monitor (G-Sync/FreeSync) @@ -49,7 +49,7 @@ There are several workarounds for this: alleviate this, you can increase **Low Processor Mode Sleep (µsec)** to ``33000`` (30 FPS) in the Editor Settings. This value determines the amount of *microseconds* between frames to render. Higher values will make the editor - feel less reactive but will help decrease CPU and GPU usage significantly. + feel less reactive, but will help decrease CPU and GPU usage significantly. - Alternatively, disable variable refresh rate on your monitor or in the graphics driver. - VRR flicker can be reduced on some displays using the **VRR Control** or **Fine Tune Dark Areas** options in your monitor's OSD. These options may