Merge branch 'godotengine:master' into master

.github/actions/godot-build/action.yml

@@ -18,12 +18,12 @@ inputs:
     required: false
   scons-cache:
     description: The SCons cache path.
-    default: ${{ github.workspace }}/.scons-cache/
+    default: ${{ github.workspace }}/.scons_cache/
   scons-cache-limit:
     description: The SCons cache size limit.
     # actions/cache has 10 GiB limit, and GitHub runners have a 14 GiB disk.
     # Limit to 7 GiB to avoid having the extracted cache fill the disk.
-    default: 7168
+    default: 7
 
 runs:
   using: composite
@@ -32,10 +32,8 @@ runs:
       shell: sh
       env:
         SCONSFLAGS: ${{ inputs.sconsflags }}
-        SCONS_CACHE: ${{ inputs.scons-cache }}
-        SCONS_CACHE_LIMIT: ${{ inputs.scons-cache-limit }}
       run: |
-        echo "Building with flags:" platform=${{ inputs.platform }} target=${{ inputs.target }} tests=${{ inputs.tests }} ${{ env.SCONSFLAGS }}
+        echo "Building with flags:" platform=${{ inputs.platform }} target=${{ inputs.target }} tests=${{ inputs.tests }} ${{ env.SCONSFLAGS }} "cache_path=${{ inputs.scons-cache }}" cache_limit=${{ inputs.scons-cache-limit }}
 
         if [ "${{ inputs.target }}" != "editor" ]; then
           # Ensure we don't include editor code in export template builds.
@@ -49,5 +47,5 @@ runs:
           export BUILD_NAME="gh"
         fi
 
-        scons platform=${{ inputs.platform }} target=${{ inputs.target }} tests=${{ inputs.tests }} ${{ env.SCONSFLAGS }}
+        scons platform=${{ inputs.platform }} target=${{ inputs.target }} tests=${{ inputs.tests }} ${{ env.SCONSFLAGS }} "cache_path=${{ inputs.scons-cache }}" cache_limit=${{ inputs.scons-cache-limit }}
         ls -l bin/

.github/actions/godot-cache-restore/action.yml

@@ -6,7 +6,7 @@ inputs:
     default: ${{ github.job }}
   scons-cache:
     description: The SCons cache path.
-    default: ${{ github.workspace }}/.scons-cache/
+    default: ${{ github.workspace }}/.scons_cache/
 
 runs:
   using: composite
@@ -29,7 +29,6 @@ runs:
         #   4. A partial match for the same base branch only (not ideal, matches any PR with the same base branch).
 
         restore-keys: |
-          ${{ inputs.cache-name }}-${{ env.GODOT_BASE_BRANCH }}-${{ github.ref }}-${{ github.sha }}
           ${{ inputs.cache-name }}-${{ env.GODOT_BASE_BRANCH }}-${{ github.ref }}
           ${{ inputs.cache-name }}-${{ env.GODOT_BASE_BRANCH }}-refs/heads/${{ env.GODOT_BASE_BRANCH }}
           ${{ inputs.cache-name }}-${{ env.GODOT_BASE_BRANCH }}

.github/actions/godot-cache-save/action.yml

@@ -6,7 +6,7 @@ inputs:
     default: ${{ github.job }}
   scons-cache:
     description: The SCons cache path.
-    default: ${{ github.workspace }}/.scons-cache/
+    default: ${{ github.workspace }}/.scons_cache/
 
 runs:
   using: composite

.github/workflows/godot_cpp_test.yml

@@ -52,9 +52,6 @@ jobs:
       #   continue-on-error: true
 
       - name: Build godot-cpp test extension
-        env: # Keep synced with godot-build.
-          SCONS_CACHE: ${{ github.workspace }}/.scons-cache/
-          SCONS_CACHE_LIMIT: 7168
         run: scons --directory=./godot-cpp/test target=template_debug dev_build=yes verbose=yes
 
       # - name: Save Godot build cache

.gitignore

@@ -77,6 +77,9 @@ venv
 __pycache__/
 *.pyc
 
+# Python modules
+.*_cache/
+
 # Documentation
 doc/_build/
 
@@ -164,9 +167,6 @@ gmon.out
 # Kdevelop
 *.kdev4
 
-# Mypy
-.mypy_cache
-
 # Qt Creator
 *.config
 *.creator

SConstruct

@@ -271,6 +271,8 @@ opts.Add(BoolVariable("scu_build", "Use single compilation unit build", False))
 opts.Add("scu_limit", "Max includes per SCU file when using scu_build (determines RAM use)", "0")
 opts.Add(BoolVariable("engine_update_check", "Enable engine update checks in the Project Manager", True))
 opts.Add(BoolVariable("steamapi", "Enable minimal SteamAPI integration for usage time tracking (editor only)", False))
+opts.Add("cache_path", "Path to a directory where SCons cache files will be stored. No value disables the cache.", "")
+opts.Add("cache_limit", "Max size (in GiB) for the SCons cache. 0 means no limit.", "0")
 
 # Thirdparty libraries
 opts.Add(BoolVariable("builtin_brotli", "Use the built-in Brotli library", True))
@@ -321,6 +323,9 @@ opts.Add("rcflags", "Custom flags for Windows resource compiler")
 # in following code (especially platform and custom_modules).
 opts.Update(env)
 
+# Setup caching logic early to catch everything.
+methods.prepare_cache(env)
+
 # Copy custom environment variables if set.
 if env["import_env_vars"]:
     for env_var in str(env["import_env_vars"]).split(","):
@@ -354,7 +359,9 @@ if env["platform"] == "":
 if env["platform"] in compatibility_platform_aliases:
     alias = env["platform"]
     platform = compatibility_platform_aliases[alias]
-    print_warning(f'Platform "{alias}" has been renamed to "{platform}" in Godot 4. Building for platform "{platform}".')
+    print_warning(
+        f'Platform "{alias}" has been renamed to "{platform}" in Godot 4. Building for platform "{platform}".'
+    )
     env["platform"] = platform
 
 # Alias for convenience.
@@ -656,40 +663,32 @@ elif methods.using_gcc(env):
             "to switch to posix threads."
         )
         Exit(255)
-    if env["debug_paths_relative"] and cc_version_major < 8:
-        print_warning("GCC < 8 doesn't support -ffile-prefix-map, disabling `debug_paths_relative` option.")
-        env["debug_paths_relative"] = False
 elif methods.using_clang(env):
     # Apple LLVM versions differ from upstream LLVM version \o/, compare
     # in https://en.wikipedia.org/wiki/Xcode#Toolchain_versions
-    if env["platform"] == "macos" or env["platform"] == "ios":
-        vanilla = methods.is_vanilla_clang(env)
-        if vanilla and cc_version_major < 6:
-            print_error(
-                "Detected Clang version older than 6, which does not fully support "
-                "C++17. Supported versions are Clang 6 and later."
-            )
-            Exit(255)
-        elif not vanilla and cc_version_major < 10:
+    if methods.is_apple_clang(env):
+        if cc_version_major < 10:
             print_error(
                 "Detected Apple Clang version older than 10, which does not fully "
                 "support C++17. Supported versions are Apple Clang 10 and later."
             )
             Exit(255)
-        if env["debug_paths_relative"] and not vanilla and cc_version_major < 12:
+        elif env["debug_paths_relative"] and cc_version_major < 12:
             print_warning(
                 "Apple Clang < 12 doesn't support -ffile-prefix-map, disabling `debug_paths_relative` option."
             )
             env["debug_paths_relative"] = False
-    elif cc_version_major < 6:
-        print_error(
-            "Detected Clang version older than 6, which does not fully support "
-            "C++17. Supported versions are Clang 6 and later."
-        )
-        Exit(255)
-    if env["debug_paths_relative"] and cc_version_major < 10:
-        print_warning("Clang < 10 doesn't support -ffile-prefix-map, disabling `debug_paths_relative` option.")
-        env["debug_paths_relative"] = False
+    else:
+        if cc_version_major < 6:
+            print_error(
+                "Detected Clang version older than 6, which does not fully support "
+                "C++17. Supported versions are Clang 6 and later."
+            )
+            Exit(255)
+        elif env["debug_paths_relative"] and cc_version_major < 10:
+            print_warning("Clang < 10 doesn't support -ffile-prefix-map, disabling `debug_paths_relative` option.")
+            env["debug_paths_relative"] = False
+
 elif env.msvc:
     # Ensure latest minor builds of Visual Studio 2017/2019.
     # https://github.com/godotengine/godot/pull/94995#issuecomment-2336464574
@@ -753,7 +752,7 @@ else:
             project_path = Dir("#").abspath
             env.Append(CCFLAGS=[f"-ffile-prefix-map={project_path}=."])
     else:
-        if methods.using_clang(env) and not methods.is_vanilla_clang(env):
+        if methods.is_apple_clang(env):
             # Apple Clang, its linker doesn't like -s.
             env.Append(LINKFLAGS=["-Wl,-S", "-Wl,-x", "-Wl,-dead_strip"])
         else:
@@ -1039,11 +1038,6 @@ GLSL_BUILDERS = {
 }
 env.Append(BUILDERS=GLSL_BUILDERS)
 
-scons_cache_path = os.environ.get("SCONS_CACHE")
-if scons_cache_path is not None:
-    CacheDir(scons_cache_path)
-    print("Scons cache enabled... (path: '" + scons_cache_path + "')")
-
 if env["compiledb"]:
     env.Tool("compilation_db")
     env.Alias("compiledb", env.CompilationDatabase())
@@ -1126,5 +1120,3 @@ def purge_flaky_files():
 
 
 atexit.register(purge_flaky_files)
-
-methods.clean_cache(env)

core/io/image.cpp

@@ -2611,23 +2611,25 @@ Image::AlphaMode Image::detect_alpha() const {
 }
 
 Error Image::load(const String &p_path) {
+	String path = ResourceUID::ensure_path(p_path);
 #ifdef DEBUG_ENABLED
-	if (p_path.begins_with("res://") && ResourceLoader::exists(p_path)) {
-		WARN_PRINT(vformat("Loaded resource as image file, this will not work on export: '%s'. Instead, import the image file as an Image resource and load it normally as a resource.", p_path));
+	if (path.begins_with("res://") && ResourceLoader::exists(path)) {
+		WARN_PRINT(vformat("Loaded resource as image file, this will not work on export: '%s'. Instead, import the image file as an Image resource and load it normally as a resource.", path));
 	}
 #endif
-	return ImageLoader::load_image(p_path, this);
+	return ImageLoader::load_image(ResourceUID::ensure_path(p_path), this);
 }
 
 Ref<Image> Image::load_from_file(const String &p_path) {
+	String path = ResourceUID::ensure_path(p_path);
 #ifdef DEBUG_ENABLED
-	if (p_path.begins_with("res://") && ResourceLoader::exists(p_path)) {
-		WARN_PRINT(vformat("Loaded resource as image file, this will not work on export: '%s'. Instead, import the image file as an Image resource and load it normally as a resource.", p_path));
+	if (path.begins_with("res://") && ResourceLoader::exists(path)) {
+		WARN_PRINT(vformat("Loaded resource as image file, this will not work on export: '%s'. Instead, import the image file as an Image resource and load it normally as a resource.", path));
 	}
 #endif
 	Ref<Image> image;
 	image.instantiate();
-	Error err = ImageLoader::load_image(p_path, image);
+	Error err = ImageLoader::load_image(path, image);
 	if (err != OK) {
 		ERR_FAIL_V_MSG(Ref<Image>(), vformat("Failed to load image. Error %d", err));
 	}

core/io/resource_uid.cpp

@@ -34,6 +34,7 @@
 #include "core/crypto/crypto_core.h"
 #include "core/io/dir_access.h"
 #include "core/io/file_access.h"
+#include "core/io/resource_loader.h"
 
 // These constants are off by 1, causing the 'z' and '9' characters never to be used.
 // This cannot be fixed without breaking compatibility; see GH-83843.
@@ -139,6 +140,21 @@ void ResourceUID::remove_id(ID p_id) {
 	unique_ids.erase(p_id);
 }
 
+String ResourceUID::uid_to_path(const String &p_uid) {
+	return singleton->get_id_path(singleton->text_to_id(p_uid));
+}
+
+String ResourceUID::path_to_uid(const String &p_path) {
+	return singleton->id_to_text(ResourceLoader::get_resource_uid(p_path));
+}
+
+String ResourceUID::ensure_path(const String &p_uid_or_path) {
+	if (p_uid_or_path.begins_with("uid://")) {
+		return uid_to_path(p_uid_or_path);
+	}
+	return p_uid_or_path;
+}
+
 Error ResourceUID::save_to_cache() {
 	String cache_file = get_cache_file();
 	if (!FileAccess::exists(cache_file)) {

core/io/resource_uid.h

@@ -73,6 +73,10 @@ class ResourceUID : public Object {
 	String get_id_path(ID p_id) const;
 	void remove_id(ID p_id);
 
+	static String uid_to_path(const String &p_uid);
+	static String path_to_uid(const String &p_path);
+	static String ensure_path(const String &p_uid_or_path);
+
 	Error load_from_cache(bool p_reset);
 	Error save_to_cache();
 	Error update_cache();

doc/classes/@GlobalScope.xml

@@ -2981,7 +2981,7 @@
 			Editing the property prompts the user for restarting the editor.
 		</constant>
 		<constant name="PROPERTY_USAGE_SCRIPT_VARIABLE" value="4096" enum="PropertyUsageFlags" is_bitfield="true">
-			The property is a script variable which should be serialized and saved in the scene file.
+			The property is a script variable. [constant PROPERTY_USAGE_SCRIPT_VARIABLE] can be used to distinguish between exported script variables from built-in variables (which don't have this usage flag). By default, [constant PROPERTY_USAGE_SCRIPT_VARIABLE] is [b]not[/b] applied to variables that are created by overriding [method Object._get_property_list] in a script.
 		</constant>
 		<constant name="PROPERTY_USAGE_STORE_IF_NULL" value="8192" enum="PropertyUsageFlags" is_bitfield="true">
 			The property value of type [Object] will be stored even if its value is [code]null[/code].

doc/classes/DirAccess.xml

@@ -14,7 +14,7 @@
 		# Static
 		DirAccess.make_dir_absolute("user://levels/world1")
 		[/codeblock]
-		[b]Note:[/b] Many resources types are imported (e.g. textures or sound files), and their source asset will not be included in the exported game, as only the imported version is used. Use [ResourceLoader] to access imported resources.
+		[b]Note:[/b] Accessing project ("res://") directories once exported may behave unexpectedly as some files are converted to engine-specific formats and their original source files may not be present in the expected PCK package. Because of this, to access resources in an exported project, it is recommended to use [ResourceLoader] instead of [FileAccess].
 		Here is an example on how to iterate through the files of a directory:
 		[codeblocks]
 		[gdscript]
@@ -116,13 +116,15 @@
 			<param index="0" name="path" type="String" />
 			<description>
 				Returns whether the target directory exists. The argument can be relative to the current directory, or an absolute path.
+				[b]Note:[/b] The returned [bool] in the editor and after exporting when used on a path in the [code]res://[/code] directory may be different. Some files are converted to engine-specific formats when exported, potentially changing the directory structure.
 			</description>
 		</method>
 		<method name="dir_exists_absolute" qualifiers="static">
 			<return type="bool" />
 			<param index="0" name="path" type="String" />
 			<description>
 				Static version of [method dir_exists]. Supports only absolute paths.
+				[b]Note:[/b] The returned [bool] in the editor and after exporting when used on a path in the [code]res://[/code] directory may be different. Some files are converted to engine-specific formats when exported, potentially changing the directory structure.
 			</description>
 		</method>
 		<method name="file_exists">
@@ -131,6 +133,7 @@
 			<description>
 				Returns whether the target file exists. The argument can be relative to the current directory, or an absolute path.
 				For a static equivalent, use [method FileAccess.file_exists].
+				[b]Note:[/b] Many resources types are imported (e.g. textures or sound files), and their source asset will not be included in the exported game, as only the imported version is used. See [method ResourceLoader.exists] for an alternative approach that takes resource remapping into account.
 			</description>
 		</method>
 		<method name="get_current_dir" qualifiers="const">
@@ -151,6 +154,7 @@
 			<description>
 				Returns a [PackedStringArray] containing filenames of the directory contents, excluding files. The array is sorted alphabetically.
 				Affected by [member include_hidden] and [member include_navigational].
+				[b]Note:[/b] The returned directories in the editor and after exporting in the [code]res://[/code] directory may differ as some files are converted to engine-specific formats when exported.
 			</description>
 		</method>
 		<method name="get_directories_at" qualifiers="static">
@@ -159,6 +163,7 @@
 			<description>
 				Returns a [PackedStringArray] containing filenames of the directory contents, excluding files, at the given [param path]. The array is sorted alphabetically.
 				Use [method get_directories] if you want more control of what gets included.
+				[b]Note:[/b] The returned directories in the editor and after exporting in the [code]res://[/code] directory may differ as some files are converted to engine-specific formats when exported.
 			</description>
 		</method>
 		<method name="get_drive_count" qualifiers="static">
@@ -194,6 +199,7 @@
 			<description>
 				Returns a [PackedStringArray] containing filenames of the directory contents, excluding directories, at the given [param path]. The array is sorted alphabetically.
 				Use [method get_files] if you want more control of what gets included.
+				[b]Note:[/b] When used on a [code]res://[/code] path in an exported project, only the files included in the PCK at the given folder level are returned. In practice, this means that since imported resources are stored in a top-level [code].godot/[/code] folder, only paths to [code].gd[/code] and [code].import[/code] files are returned (plus a few other files, such as [code]project.godot[/code] or [code]project.binary[/code] and the project icon). In an exported project, the list of returned files will also vary depending on [member ProjectSettings.editor/export/convert_text_resources_to_binary].
 			</description>
 		</method>
 		<method name="get_next">

doc/classes/DisplayServer.xml

@@ -237,7 +237,7 @@
 			<return type="int" />
 			<param index="0" name="rect" type="Rect2" />
 			<description>
-				Returns index of the screen which contains specified rectangle.
+				Returns the index of the screen that overlaps the most with the given rectangle. Returns [code]-1[/code] if the rectangle doesn't overlap with any screen or has no area.
 			</description>
 		</method>
 		<method name="get_swap_cancel_ok">

doc/classes/EditorTranslationParserPlugin.xml

@@ -99,6 +99,14 @@
 	<tutorials>
 	</tutorials>
 	<methods>
+		<method name="_get_comments" qualifiers="virtual">
+			<return type="void" />
+			<param index="0" name="msgids_comment" type="String[]" />
+			<param index="1" name="msgids_context_plural_comment" type="String[]" />
+			<description>
+				If overridden, called after [method _parse_file] to get comments for the parsed entries. This method should fill the arrays with the same number of elements and in the same order as [method _parse_file].
+			</description>
+		</method>
 		<method name="_get_recognized_extensions" qualifiers="virtual const">
 			<return type="PackedStringArray" />
 			<description>