diff --git a/about/faq.rst b/about/faq.rst index 451f8b0f5..1e837a279 100644 --- a/about/faq.rst +++ b/about/faq.rst @@ -289,6 +289,18 @@ developer experiences as a whole. Bonus points for bringing screenshots, concrete numbers, test cases, or example projects (if applicable). +Is it possible to use Godot as a library? +----------------------------------------- + +Godot is meant to be used with its editor. We recommend you give it a try, as it +will most likely save you time in the long term. There are no plans to make +Godot usable as a library, as it would make the rest of the engine more +convoluted and difficult to use for casual users. + +If you want to use a rendering library, look into using an established rendering +engine instead. Keep in mind rendering engines usually have smaller communities +compared to Godot. This will make it more difficult to find answers to your +questions. Why does Godot not use STL (Standard Template Library) ------------------------------------------------------ diff --git a/conf.py b/conf.py index 60af3f0b6..7438480ed 100644 --- a/conf.py +++ b/conf.py @@ -101,6 +101,8 @@ from sphinx.highlighting import lexers lexers["gdscript"] = GDScriptLexer() # fmt: on +smartquotes = False + # Pygments (syntax highlighting) style to use pygments_style = "sphinx" highlight_language = "gdscript" diff --git a/development/compiling/compiling_for_osx.rst b/development/compiling/compiling_for_osx.rst index d9754a2f5..68eb9e247 100644 --- a/development/compiling/compiling_for_osx.rst +++ b/development/compiling/compiling_for_osx.rst @@ -30,9 +30,19 @@ For compiling under macOS, the following is required: Compiling --------- -Start a terminal, go to the root directory of the engine source code and type:: +Start a terminal, go to the root directory of the engine source code. - scons platform=osx --jobs=$(sysctl -n hw.logicalcpu) +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 (only for Godot 3.2.3+):: + + 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:: + + 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 @@ -46,11 +56,11 @@ manager. 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 ``scons p=osx 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.tools.64 Godot.app/Contents/MacOS/Godot + cp bin/godot.osx.opt.tools.universal Godot.app/Contents/MacOS/Godot chmod +x Godot.app/Contents/MacOS/Godot Compiling a headless/server build diff --git a/development/compiling/introduction_to_the_buildsystem.rst b/development/compiling/introduction_to_the_buildsystem.rst index c8359b614..c31764f73 100644 --- a/development/compiling/introduction_to_the_buildsystem.rst +++ b/development/compiling/introduction_to_the_buildsystem.rst @@ -212,6 +212,18 @@ directory paths containing such modules: :ref:`doc_custom_modules_in_c++` +Cleaning generated files +------------------------ + +Sometimes, you may encounter an error due to generated files being present. You +can remove them by using ``scons --clean ``, where ```` is the +list of build options you've used to build Godot previously. + +Alternatively, you can use ``git clean -fixd`` which will clean build artifacts +for all platforms and configurations. Beware, as this will remove all untracked +and ignored files in the repository. Don't run this command if you have +uncommitted work! + Other build options ------------------- diff --git a/development/cpp/binding_to_external_libraries.rst b/development/cpp/binding_to_external_libraries.rst index d5818b8b6..7fbcc2dcc 100644 --- a/development/cpp/binding_to_external_libraries.rst +++ b/development/cpp/binding_to_external_libraries.rst @@ -8,8 +8,8 @@ Modules The Summator example in :ref:`doc_custom_modules_in_c++` is great for small, custom modules, but what if you want to use a larger, external library? -Let's look at an example using Festival, a speech synthesis (text-to-speech) -library written in C++. +Let's look at an example using `Festival `_, +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: @@ -163,11 +163,20 @@ environment's paths: .. code-block:: python - env_tts.Append(CPPPATH=["speech_tools/include", "festival/src/include"]) # this is a path relative to /modules/tts/ - # http://www.cstr.ed.ac.uk/projects/festival/manual/festival_28.html#SEC132 <-- Festival library documentation - env_tts.Append(LIBPATH=['libpath']) # this is a path relative to /modules/tts/ where your .a library files reside - # You should check with the documentation of the external library to see which library files should be included/linked - env_tts.Append(LIBS=['Festival', 'estools', 'estbase', 'eststring']) + # These paths are relative to /modules/tts/ + env_tts.Append(CPPPATH=["speech_tools/include", "festival/src/include"]) + + # LIBPATH and LIBS need to be set on the real "env" (not the clone) + # to link the specified libraries to the Godot executable. + + # This is a path relative to /modules/tts/ where your .a libraries reside. + # If you are compiling the module externally (not in the godot source tree), + # these will need to be full paths. + env.Append(LIBPATH=['libpath']) + + # 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). diff --git a/development/cpp/common_engine_methods_and_macros.rst b/development/cpp/common_engine_methods_and_macros.rst index 48e6e1478..31493e76e 100644 --- a/development/cpp/common_engine_methods_and_macros.rst +++ b/development/cpp/common_engine_methods_and_macros.rst @@ -70,7 +70,7 @@ Internationalize a string There are two types of internationalization in Godot's codebase: - ``TTR()``: **Editor ("tools") translations** will only be processed in the - editor. If an user uses the same text in one of their projects, it won't be + editor. If a user uses the same text in one of their projects, it won't be translated if they provide a translation for it. When contributing to the engine, this is generally the macro you should use for localizable strings. - ``RTR()``: **Run-time translations** will be automatically localized in @@ -102,7 +102,7 @@ To insert placeholders in localizable strings, wrap the localization macro in a Clamp a value ------------- -Godot has provides macros for clamping a value with a lower bound (``MAX``), an +Godot provides macros for clamping a value with a lower bound (``MAX``), an upper bound (``MIN``) or both (``CLAMP``): .. code-block:: cpp diff --git a/development/cpp/custom_modules_in_cpp.rst b/development/cpp/custom_modules_in_cpp.rst index 2ab11901f..48ccc8b47 100644 --- a/development/cpp/custom_modules_in_cpp.rst +++ b/development/cpp/custom_modules_in_cpp.rst @@ -342,22 +342,30 @@ library that will be dynamically loaded when starting our game's binary. # First, create a custom env for the shared library. module_env = env.Clone() - module_env.Append(CCFLAGS=['-fPIC']) # Needed to compile shared library - # We don't want godot's dependencies to be injected into our shared library. + + # Position-independent code is required for a shared library. + module_env.Append(CCFLAGS=['-fPIC']) + + # Don't inject Godot's dependencies into our shared library. module_env['LIBS'] = [] - # Now define the shared library. Note that by default it would be built - # into the module's folder, however it's better to output it into `bin` - # next to the Godot binary. + # Define the shared library. By default, it would be built in the module's + # folder, however it's better to output it into `bin` next to the + # Godot binary. shared_lib = module_env.SharedLibrary(target='#bin/summator', source=sources) - # Finally, notify the main env it has our shared library as a new dependency. - # To do so, SCons wants the name of the lib with it custom suffixes + # Finally, notify the main build environment it now has our shared library + # as a new dependency. + + # LIBPATH and LIBS need to be set on the real "env" (not the clone) + # to link the specified libraries to the Godot executable. + + env.Append(LIBPATH=['#bin']) + + # SCons wants the name of the library with it custom suffixes # (e.g. ".x11.tools.64") but without the final ".so". - # We pass this along with the directory of our library to the main env. shared_lib_shim = shared_lib[0].name.rsplit('.', 1)[0] env.Append(LIBS=[shared_lib_shim]) - env.Append(LIBPATH=['#bin']) 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 diff --git a/getting_started/editor/external_editor.rst b/getting_started/editor/external_editor.rst index 32206013b..e5cb069af 100644 --- a/getting_started/editor/external_editor.rst +++ b/getting_started/editor/external_editor.rst @@ -3,6 +3,10 @@ Using an external text editor ============================== +.. warning:: + + `External editors are currently incompatible with Godot's "Sync Script Changes" feature. `__ + Godot can be used with an external text editor, such as Sublime Text or Visual Studio Code. To enable an external text editor, browse to the relevant editor settings via: ``Editor -> Editor Settings -> Text Editor -> External`` diff --git a/getting_started/scripting/gdscript/gdscript_basics.rst b/getting_started/scripting/gdscript/gdscript_basics.rst index 447777412..2d17eabad 100644 --- a/getting_started/scripting/gdscript/gdscript_basics.rst +++ b/getting_started/scripting/gdscript/gdscript_basics.rst @@ -629,7 +629,7 @@ expressions and must be assigned on initialization. const E = [1, 2, 3, 4][0] # Constant expression: 1. const F = sin(20) # 'sin()' can be used in constant expressions. const G = x + 20 # Invalid; this is not a constant expression! - const H = A + 20 # Constant expression: 25. + const H = A + 20 # Constant expression: 25 (`A` is a constant). Although the type of constants is inferred from the assigned value, it's also possible to add explicit type specification:: @@ -639,6 +639,12 @@ possible to add explicit type specification:: Assigning a value of an incompatible type will raise an error. +.. note:: + + Since arrays and dictionaries are passed by reference, constants are "flat". + This means that if you declare a constant array or dictionary, it can still + be modified afterwards. They can't be reassigned with another value though. + Enums ^^^^^ @@ -1571,7 +1577,7 @@ multiple times, you can yield to the ``completed`` signal conditionally: return result This ensures that the function returns whatever it was supposed to return -irregardless of whether coroutines were used internally. Note that using +regardless of whether coroutines were used internally. Note that using ``while`` would be redundant here as the ``completed`` signal is only emitted when the function didn't yield anymore. diff --git a/getting_started/workflow/best_practices/scenes_versus_scripts.rst b/getting_started/workflow/best_practices/scenes_versus_scripts.rst index 669804210..03c289e7c 100644 --- a/getting_started/workflow/best_practices/scenes_versus_scripts.rst +++ b/getting_started/workflow/best_practices/scenes_versus_scripts.rst @@ -41,7 +41,7 @@ a change in API: public class Game : Node { public readonly Script MyNodeScr = (Script)ResourceLoader.Load("MyNode.cs"); - public readonly PackedScene MySceneScn = (PackedScene)ResourceLoader.load("MyScene.tscn"); + public readonly PackedScene MySceneScn = (PackedScene)ResourceLoader.Load("MyScene.tscn"); public Node ANode; public Node MyNode; public Node MyScene; diff --git a/getting_started/workflow/export/exporting_for_android.rst b/getting_started/workflow/export/exporting_for_android.rst index f7950f623..c3d274bb0 100644 --- a/getting_started/workflow/export/exporting_for_android.rst +++ b/getting_started/workflow/export/exporting_for_android.rst @@ -31,7 +31,7 @@ macOS, you can find it in the ``~/.android`` directory). If you can't find it or need to generate one, the keytool command from the JDK can be used for this purpose:: - keytool -keyalg RSA -genkeypair -alias androiddebugkey -keypass android -keystore debug.keystore -storepass android -dname "CN=Android Debug,O=Android,C=US" -validity 9999 + keytool -keyalg RSA -genkeypair -alias androiddebugkey -keypass android -keystore debug.keystore -storepass android -dname "CN=Android Debug,O=Android,C=US" -validity 9999 -deststoretype pkcs12 This will create a ``debug.keystore`` file in your current directory. You should move it to a memorable location such as ``%USERPROFILE%\.android\``, because you will need its location in a later step. For more information on ``keytool`` usage, see `this Q&A article `__. diff --git a/tutorials/inputs/input_examples.rst b/tutorials/inputs/input_examples.rst index b2c981df1..34437ce43 100644 --- a/tutorials/inputs/input_examples.rst +++ b/tutorials/inputs/input_examples.rst @@ -194,7 +194,7 @@ the :kbd:`T`: { if (inputEvent is InputEventKey keyEvent && keyEvent.Pressed) { - if ((Keylist)keyEvent.Scancode == KeyList.T) + if ((KeyList)keyEvent.Scancode == KeyList.T) { GD.Print("T was pressed"); } diff --git a/tutorials/platform/android_in_app_purchases.rst b/tutorials/platform/android_in_app_purchases.rst index 999c8ae0c..88975c749 100644 --- a/tutorials/platform/android_in_app_purchases.rst +++ b/tutorials/platform/android_in_app_purchases.rst @@ -116,7 +116,7 @@ Full example: :: - var query = payment.queryPurchases() + var query = payment.queryPurchases("inapp") # Or "subs" for subscriptions if query.status == OK: for purchase in query.purchases: if purchase.sku == "my_iap_item": @@ -135,7 +135,7 @@ acknowledges a purchase. :: - var query = payment.queryPurchases() + var query = payment.queryPurchases("inapp") # Or "subs" for subscriptions if query.status == OK: for purchase in query.purchases: if purchase.sku == "my_consumable_iap_item": diff --git a/tutorials/plugins/editor/import_plugins.rst b/tutorials/plugins/editor/import_plugins.rst index 675b83d3d..290db791b 100644 --- a/tutorials/plugins/editor/import_plugins.rst +++ b/tutorials/plugins/editor/import_plugins.rst @@ -178,7 +178,7 @@ good practice to use an enum so you can refer to them using names. tool extends EditorImportPlugin - enum Presets { PRESET_DEFAULT } + enum Presets { DEFAULT } ... @@ -199,7 +199,7 @@ now, but we can make this method future-proof by returning the size of our func get_preset_name(preset): match preset: - PRESET_DEFAULT: + Presets.DEFAULT: return "Default" _: return "Unknown" @@ -222,7 +222,7 @@ you do this you have to be careful when you add more presets. func get_import_options(preset): match preset: - PRESET_DEFAULT: + Presets.DEFAULT: return [{ "name": "use_red_anyway", "default_value": false diff --git a/tutorials/shading/migrating_to_godot_shader_language.rst b/tutorials/shading/migrating_to_godot_shader_language.rst index 0f7eeee85..9ac3280c8 100644 --- a/tutorials/shading/migrating_to_godot_shader_language.rst +++ b/tutorials/shading/migrating_to_godot_shader_language.rst @@ -70,8 +70,8 @@ fragment shader, rename ``main`` to ``fragment``. Constants ^^^^^^^^^ -Godot currently does not support constants. You can fake the functionality by using a uniform initialized -to the value, but you will not benefit from the increased speed from using a constant. +Global array constants are not supported in Godot 3.2.x. You can fake the functionality by using a uniform +initialized to the value, but you will not benefit from the increased speed from using a constant. Macros ^^^^^^ @@ -133,7 +133,7 @@ Types ^^^^^ Shadertoy uses the webgl spec, so it runs a slightly different version of GLSL. However, it still -has the regular types, including `Constants`_ and macros. +has the regular types, including constants and macros. mainImage ^^^^^^^^^ @@ -200,7 +200,7 @@ Types ^^^^^ The Book of Shaders uses the webgl spec, so it runs a slightly different version of GLSL. However, it still -has the regular types, including `Constants`_ and macros. +has the regular types, including constants and macros. Main ^^^^ diff --git a/tutorials/shading/shading_reference/spatial_shader.rst b/tutorials/shading/shading_reference/spatial_shader.rst index b859dfdec..ed47e1353 100644 --- a/tutorials/shading/shading_reference/spatial_shader.rst +++ b/tutorials/shading/shading_reference/spatial_shader.rst @@ -293,7 +293,7 @@ Below is an example of a custom light function using a Lambertian lighting model .. code-block:: glsl void light() { - DIFFUSE_LIGHT += dot(NORMAL, LIGHT) * ATTENUATION * ALBEDO; + DIFFUSE_LIGHT += clamp(dot(NORMAL, LIGHT), 0.0, 1.0) * ATTENUATION * ALBEDO; } If you want the lights to add together, add the light contribution to ``DIFFUSE_LIGHT`` using ``+=``, rather than overwriting it. diff --git a/tutorials/vr/img/quest_export_settings.png b/tutorials/vr/img/quest_export_settings.png index 91896f163..091cff36e 100644 Binary files a/tutorials/vr/img/quest_export_settings.png and b/tutorials/vr/img/quest_export_settings.png differ diff --git a/tutorials/vr/vr_primer.rst b/tutorials/vr/vr_primer.rst index 041b21303..25aadfb3c 100644 --- a/tutorials/vr/vr_primer.rst +++ b/tutorials/vr/vr_primer.rst @@ -127,6 +127,9 @@ in the `GodotVR Repository `_. (desktop headsets only). * `Godot OpenHMD `_ supports OpenHMD, an open source API and drivers for headsets. +* `Godot OpenXR `_ supports OpenXR, an open standard + for VR and AR software. This plugin is early in development, only supports Linux and requires + extra setup described in the repository. These plugins can be downloaded from GitHub or the Godot Asset Library.