Enhance cache modes in resource loading

- Unify documentation, hoping to clear misconcepctions about about propagation of the cache mode across dependant loads.
- Clarify in docs that `CACHE_MODE_REPLACE` now also works on the main resource (from #87008).
- Add two recursive modes, counterparts of `CACHE_MODE_REPLACE` and `CACHE_MODE_IGNORE`, since it seems some need them (see #59669, #82830).
- Let resources, even loaded with one of the ignore-cache modes, get a path, which is useful for tools.

1 files changed, 9 insertions, 5 deletions

diff --git a/core/io/resource_loader.cpp b/core/io/resource_loader.cpp
index a3fc7bc370..ff563a35b2 100644
--- a/core/io/resource_loader.cpp
+++ b/core/io/resource_loader.cpp
@@ -188,6 +188,8 @@ void ResourceFormatLoader::_bind_methods() {
 	BIND_ENUM_CONSTANT(CACHE_MODE_IGNORE);
 	BIND_ENUM_CONSTANT(CACHE_MODE_REUSE);
 	BIND_ENUM_CONSTANT(CACHE_MODE_REPLACE);
+	BIND_ENUM_CONSTANT(CACHE_MODE_IGNORE_DEEP);
+	BIND_ENUM_CONSTANT(CACHE_MODE_REPLACE_DEEP);
 
 	GDVIRTUAL_BIND(_get_recognized_extensions);
 	GDVIRTUAL_BIND(_recognize_path, "path", "type");
@@ -339,9 +341,11 @@ void ResourceLoader::_thread_load_function(void *p_userdata) {
 		load_task.cond_var = nullptr;
 	}
 
+	bool ignoring = load_task.cache_mode == ResourceFormatLoader::CACHE_MODE_IGNORE || load_task.cache_mode == ResourceFormatLoader::CACHE_MODE_IGNORE_DEEP;
+	bool replacing = load_task.cache_mode == ResourceFormatLoader::CACHE_MODE_REPLACE || load_task.cache_mode == ResourceFormatLoader::CACHE_MODE_REPLACE_DEEP;
 	if (load_task.resource.is_valid()) {
-		if (load_task.cache_mode != ResourceFormatLoader::CACHE_MODE_IGNORE) {
-			if (load_task.cache_mode == ResourceFormatLoader::CACHE_MODE_REPLACE) {
+		if (!ignoring) {
+			if (replacing) {
 				Ref<Resource> old_res = ResourceCache::get_ref(load_task.local_path);
 				if (old_res.is_valid() && old_res != load_task.resource) {
 					// If resource is already loaded, only replace its data, to avoid existing invalidating instances.
@@ -349,8 +353,8 @@ void ResourceLoader::_thread_load_function(void *p_userdata) {
 					load_task.resource = old_res;
 				}
 			}
-			load_task.resource->set_path(load_task.local_path, load_task.cache_mode == ResourceFormatLoader::CACHE_MODE_REPLACE);
-		} else if (!load_task.local_path.is_resource_file()) {
+			load_task.resource->set_path(load_task.local_path, replacing);
+		} else {
 			load_task.resource->set_path_cache(load_task.local_path);
 		}
 
@@ -370,7 +374,7 @@ void ResourceLoader::_thread_load_function(void *p_userdata) {
 		if (_loaded_callback) {
 			_loaded_callback(load_task.resource, load_task.local_path);
 		}
-	} else if (load_task.cache_mode != ResourceFormatLoader::CACHE_MODE_IGNORE) {
+	} else if (!ignoring) {
 		Ref<Resource> existing = ResourceCache::get_ref(load_task.local_path);
 		if (existing.is_valid()) {
 			load_task.resource = existing;