gdharness 1.1.21 → 1.1.22

package/build/godot/addons/gdharness_runtime/serialisation.gd

@@ -53,6 +53,9 @@ const LIST_TYPES: Array[int] = [
 # type it wanted.
 const SERIALISERS: Dictionary = {
 	TYPE_NIL: "_serialize_nil",
+	TYPE_FLOAT: "_serialize_float",
+	TYPE_PACKED_FLOAT32_ARRAY: "_serialize_floats",
+	TYPE_PACKED_FLOAT64_ARRAY: "_serialize_floats",
 	TYPE_VECTOR2: "_serialize_vector2",
 	TYPE_VECTOR2I: "_serialize_vector2i",
 	TYPE_VECTOR3: "_serialize_vector3",
@@ -105,6 +108,8 @@ const BUILDERS: Dictionary = {
 	"Color": "_build_color",
 	"NodePath": "_build_node_path",
 	"PackedByteArray": "_build_bytes",
+	"float": "_build_float",
+	"Dictionary": "_build_dictionary",
 }
 
 # What each tag has to carry before it is built. A tag naming a type whose keys are not there is a
@@ -130,6 +135,8 @@ const REQUIRED: Dictionary = {
 	"Color": [["r", "g", "b"]],
 	"NodePath": [["path"]],
 	"PackedByteArray": [["base64"]],
+	"float": [["value"]],
+	"Dictionary": [["entries"]],
 }
 
 
@@ -145,7 +152,58 @@ func serialize_value(value: Variant) -> Variant:
 	if typeof(value) == TYPE_OBJECT and not is_instance_valid(value):
 		return null
 	var serialiser: String = SERIALISERS.get(typeof(value), "")
-	return call(serialiser, value) if not serialiser.is_empty() else value
+	if serialiser.is_empty():
+		return value
+	var carried: Variant = call(serialiser, value)
+	# The fixed shapes carry their components as bare floats, so an infinite one in a Vector2 is
+	# tagged here; containers reach their members through this function already.
+	return carried if typeof(value) in [TYPE_ARRAY, TYPE_DICTIONARY] else _finite(carried)
+
+
+# [param carried] with every non-finite float in it tagged. JSON has no spelling for infinity or
+# NaN: the engine writes 1e99999 and null, and the server, reading 1e99999 as Infinity, writes it
+# back out as null, so a property holding INF was answered as holding nothing.
+func _finite(carried: Variant) -> Variant:
+	if carried is float:
+		var number: float = carried
+		return _serialize_float(number)
+	if carried is Dictionary:
+		var fields: Dictionary = carried
+		var tagged: Dictionary = {}
+		for key: Variant in fields:
+			tagged[key] = _finite(fields[key])
+		return tagged
+	if carried is Array:
+		var items: Array = carried
+		var tagged_items: Array = []
+		for item: Variant in items:
+			tagged_items.append(_finite(item))
+		return tagged_items
+	return carried
+
+
+func _serialize_float(value: float) -> Variant:
+	if is_finite(value):
+		return value
+	return {"_type": "float", "value": "nan" if is_nan(value) else ("inf" if value > 0 else "-inf")}
+
+
+# A packed float array stays the JSON list it is unless something in it has no JSON spelling.
+func _serialize_floats(value: Variant) -> Variant:
+	var numbers: Array = []
+	if value is PackedFloat32Array:
+		var single: PackedFloat32Array = value
+		numbers = Array(single)
+	else:
+		var double: PackedFloat64Array = value
+		numbers = Array(double)
+	for number: float in numbers:
+		if not is_finite(number):
+			var items: Array = []
+			for each: float in numbers:
+				items.append(_serialize_float(each))
+			return items
+	return value
 
 
 # Rebuilds a Godot value from the shape serialize_value gave it.
@@ -181,9 +239,27 @@ func deserialize_value(value: Variant) -> Variant:
 	var needed: Array = REQUIRED.get(tag, [])
 	if builder.is_empty() or not _carries(fields, needed):
 		return fields
+	if tag == "float" and str(fields["value"]) not in ["inf", "-inf", "nan"]:
+		return fields
+	if tag == "Dictionary" and not pairs(fields["entries"]):
+		return fields
 	return call(builder, fields)
 
 
+## Whether [param entries] is a list of [key, value] pairs, as a Dictionary tag carries them.
+static func pairs(entries: Variant) -> bool:
+	if not entries is Array:
+		return false
+	var listed: Array = entries
+	for entry: Variant in listed:
+		if not entry is Array:
+			return false
+		var pair: Array = entry
+		if pair.size() != 2:
+			return false
+	return true
+
+
 ## Whether two values can be compared without the comparison itself failing.
 ##
 ## GDScript's `==` is not total. An Object against a String is a hard error rather than false, and
@@ -193,16 +269,19 @@ func deserialize_value(value: Variant) -> Variant:
 ## nothing anywhere naming the argument that did it. A wrong argument costs a refusal, never the
 ## session's game.
 ##
-## Only an object is special. Every other pair the engine answers, false where they differ, and
-## refusing those would refuse calls that work: an int against a float is the same number to a
-## caller waiting for 1 on a property holding 1.0.
+## Measured on 4.7.2 over every pair of built-in types: two values of different types compare only
+## as an int against a float, a String against a StringName, or anything against null. Every other
+## pair is that error, a word against a number as much as an object against a word, and so is a bool
+## against an int and a NodePath against a String. An int against a float is kept because it is the
+## same number to a caller waiting for 1 on a property holding 1.0.
 static func comparable(one: Variant, other: Variant) -> bool:
 	var left: int = typeof(one)
 	var right: int = typeof(other)
-	if left != TYPE_OBJECT and right != TYPE_OBJECT:
+	if left == right or left == TYPE_NIL or right == TYPE_NIL:
 		return true
-	# An object compares with another object and with null. Anything else is the error above.
-	return (left == TYPE_OBJECT or left == TYPE_NIL) and (right == TYPE_OBJECT or right == TYPE_NIL)
+	var numbers: Array[int] = [TYPE_INT, TYPE_FLOAT]
+	var texts: Array[int] = [TYPE_STRING, TYPE_STRING_NAME]
+	return (left in numbers and right in numbers) or (left in texts and right in texts)
 
 
 ## Whether [param value] can be given to something declared as [param type] without damage.
@@ -400,7 +479,16 @@ func _serialize_signal(value: Signal) -> Dictionary:
 	return described
 
 
+## A dictionary keyed by text as itself, and any other as its entries. JSON keys are text, so an
+## int or Vector2 key was answered as its text, and a dictionary read and written back had its keys
+## replaced by words: `{1: "a"}` came back as `{"1": "a"}`.
 func _serialize_dictionary(value: Dictionary) -> Dictionary:
+	var texts: bool = value.keys().all(func(key: Variant) -> bool: return key is String or key is StringName)
+	if not texts:
+		var entries: Array = []
+		for key: Variant in value:
+			entries.append([serialize_value(key), serialize_value(value[key])])
+		return {"_type": "Dictionary", "entries": entries}
 	var serialised: Dictionary = {}
 	for key: Variant in value:
 		serialised[str(key)] = serialize_value(value[key])
@@ -621,6 +709,27 @@ func _build_bytes(fields: Dictionary) -> PackedByteArray:
 	return Marshalls.base64_to_raw(str(fields.get("base64", "")))
 
 
+func _build_float(fields: Dictionary) -> float:
+	return Read.as_float(fields)
+
+
+## The entries of a dictionary whose keys are not all text. JSON carries every number as a float,
+## and a dictionary keys 1.0 apart from 1, so a whole-number key is built as an int: the key a
+## game uses far more often, and one JSON cannot tell from the float.
+func _build_dictionary(fields: Dictionary) -> Dictionary:
+	var built: Dictionary = {}
+	var entries: Array = fields["entries"]
+	for entry: Variant in entries:
+		var pair: Array = entry
+		var key: Variant = deserialize_value(pair[0])
+		if key is float:
+			var number: float = key
+			if is_finite(number) and number == floorf(number):
+				key = int(number)
+		built[key] = deserialize_value(pair[1])
+	return built
+
+
 ## One component of a compound value, as the type its constructor wants.
 ##
 ## Their own functions because a constructor refuses a Variant under `unsafe_call_argument`, and

package/build/godot/operations/audio_buses.gd

@@ -20,17 +20,28 @@ func create_audio_bus(params: Dictionary) -> Dictionary:
 	var parent_idx: int = Read.as_int(params.get("parent_bus_index", 0))
 	if parent_idx < 0 or parent_idx >= AudioServer.bus_count:
 		return _log.failure("No bus at index " + str(parent_idx))
-
-	AudioServer.add_bus(parent_idx + 1)
-	var new_idx: int = AudioServer.bus_count - 1
+	# Sends are by name, so a second bus with one would leave every send to it meaning either.
+	var existing: int = AudioServer.get_bus_index(bus_name)
+	if existing != -1:
+		return _log.failure("A bus named " + bus_name + " already exists, at index " + str(existing))
+
+	# Right after the bus it sends to, because a bus can only send to one before it. The engine
+	# inserts there and moves every later bus down one, so the new bus is at that index: taking the
+	# last index named and rewired whichever bus had been last, and answered with it.
+	var new_idx: int = parent_idx + 1
+	AudioServer.add_bus(new_idx)
 	AudioServer.set_bus_name(new_idx, bus_name)
-	if parent_idx > 0:
-		AudioServer.set_bus_send(new_idx, AudioServer.get_bus_name(parent_idx))
+	AudioServer.set_bus_send(new_idx, AudioServer.get_bus_name(parent_idx))
 
 	var layout: String = _save_layout()
 	if layout.is_empty():
 		return {}
-	return {"bus": _bus(new_idx), "layout": layout}
+	# Every bus, because the ones after the new one have moved and a caller holding their old
+	# indices would address the wrong bus next.
+	var buses: Array[Dictionary] = []
+	for i: int in range(AudioServer.bus_count):
+		buses.append(_bus(i))
+	return {"bus": _bus(new_idx), "buses": buses, "layout": layout}
 
 
 func get_audio_buses(_params: Dictionary) -> Dictionary:
@@ -52,17 +63,42 @@ func set_audio_bus_effect(params: Dictionary) -> Dictionary:
 	if effect == null:
 		return _log.failure("Unknown effect type: " + effect_type)
 
-	# The slot has to exist before an effect can be placed at that index.
-	while AudioServer.get_bus_effect_count(bus_idx) <= effect_idx:
-		AudioServer.add_bus_effect(bus_idx, AudioEffectAmplify.new())
-
+	# The slot holds this effect afterwards: the one there is replaced, and one past the last is
+	# added. The engine's add inserts, so the effect in the slot was pushed along rather than
+	# replaced, and a slot past the end was reached by padding the bus with Amplify effects nobody
+	# asked for.
+	var count: int = AudioServer.get_bus_effect_count(bus_idx)
+	if effect_idx < 0 or effect_idx > count:
+		return _log.failure(
+			(
+				"Bus "
+				+ str(bus_idx)
+				+ " has "
+				+ str(count)
+				+ (" effect" if count == 1 else " effects")
+				+ ", so effect_index can be 0 to "
+				+ str(count)
+				+ ", where "
+				+ str(count)
+				+ " adds one after the last"
+			)
+		)
+	var replaced: String = ""
+	if effect_idx < count:
+		replaced = AudioServer.get_bus_effect(bus_idx, effect_idx).get_class()
+		AudioServer.remove_bus_effect(bus_idx, effect_idx)
 	AudioServer.add_bus_effect(bus_idx, effect, effect_idx)
 	AudioServer.set_bus_effect_enabled(bus_idx, effect_idx, enabled)
 
 	var layout: String = _save_layout()
 	if layout.is_empty():
 		return {}
-	return {"bus": _bus(bus_idx), "effect_index": effect_idx, "effect_type": effect_type, "layout": layout}
+	var answer: Dictionary = {
+		"bus": _bus(bus_idx), "effect_index": effect_idx, "effect_type": effect.get_class(), "layout": layout
+	}
+	if not replaced.is_empty():
+		answer["replaced"] = replaced
+	return answer
 
 
 func set_audio_bus_volume(params: Dictionary) -> Dictionary:

package/build/godot/operations/class_cache.gd

@@ -21,7 +21,8 @@ func _init(p_log: Log) -> void:
 
 
 func refresh_class_cache(_params: Dictionary) -> Dictionary:
-	var before: Dictionary = _entries_by_class(_read_cache())
+	var cached: Array = _read_cache()
+	var before: Dictionary = _entries_by_class(cached)
 
 	var entries: Array = []
 	var skipped: Array[Dictionary] = []
@@ -29,6 +30,18 @@ func refresh_class_cache(_params: Dictionary) -> Dictionary:
 		var entry: Dictionary = _entry_for(path, skipped)
 		if not entry.is_empty():
 			entries.append(entry)
+	# Another language's classes are kept while their files are there. Only GDScript is read here and
+	# the list is written whole, so a C# project's global classes were dropped from it and answered as
+	# removed, and nothing started next could resolve them.
+	var carried: Array[String] = []
+	for entry: Variant in cached:
+		if not entry is Dictionary:
+			continue
+		var listed: Dictionary = entry
+		var language: String = str(listed.get("language", "GDScript"))
+		if language != "GDScript" and FileAccess.file_exists(str(listed.get("path", ""))):
+			entries.append(listed)
+			carried.append(str(listed.get("class", "")))
 	# By name as text: StringName's own order is by identity, not by spelling.
 	entries.sort_custom(func(a: Dictionary, b: Dictionary) -> bool: return str(a["class"]) < str(b["class"]))
 
@@ -56,7 +69,7 @@ func refresh_class_cache(_params: Dictionary) -> Dictionary:
 		if not after.has(name):
 			removed.append(name)
 
-	return {
+	var answer: Dictionary = {
 		"path": CACHE_PATH,
 		"classes": entries.size(),
 		"added": added,
@@ -64,6 +77,9 @@ func refresh_class_cache(_params: Dictionary) -> Dictionary:
 		"changed": changed,
 		"skipped": skipped,
 	}
+	if not carried.is_empty():
+		answer["carried"] = carried
+	return answer
 
 
 # The cache entry for one script, or empty for a script with no class_name.

package/build/godot/operations/dependencies.gd

@@ -4,6 +4,14 @@ const Patterns = preload("patterns.gd")
 const Read = preload("reading.gd")
 const FileWalk = preload("file_walk.gd")
 const Log = preload("logger.gd")
+const ResourceFiles = preload("resource_files.gd")
+
+## What a reverse search reads unless told otherwise: the resource and code files, and the settings
+## files that name resources, "godot" for project.godot, "cfg" for plugin.cfg and export_presets.cfg,
+## and "import" for the sidecars that name import scripts and external materials.
+const DEFAULT_USAGE_KINDS: Array[String] = ["tscn", "tres", "gd", "gdshader", "godot", "cfg", "import"]
+## One string literal of either quote, its contents captured by the one it opened with.
+const STRING_LITERAL: String = "\"((?:[^\"\\\\]|\\\\.)*)\"|'((?:[^'\\\\]|\\\\.)*)'"
 
 # What a dependency reference looks like in source, and how the path is read out of each form.
 const REFERENCE_PATTERNS: Array[String] = [
@@ -106,7 +114,7 @@ func get_dependencies(params: Dictionary) -> Dictionary:
 # preload it, and for a script with a class_name, every use of that name.
 func find_resource_usages(params: Dictionary) -> Dictionary:
 	var resource_path: String = str(params.get("resource_path", ""))
-	var file_types: Array = params.get("file_types", ["tscn", "tres", "gd", "gdshader"])
+	var file_types: Array = params.get("file_types", DEFAULT_USAGE_KINDS)
 
 	if not resource_path.begins_with("res://"):
 		resource_path = "res://" + resource_path
@@ -116,14 +124,14 @@ func find_resource_usages(params: Dictionary) -> Dictionary:
 	_log.info("Finding usages of: " + resource_path)
 
 	var class_name_declared: String = _declared_class_name(resource_path)
-	var by_path: RegEx = Patterns.compiled('"(res://)?' + _regex_escaped(resource_path.substr(6)) + '"')
 	var by_class: RegEx = null
 	if not class_name_declared.is_empty():
 		by_class = Patterns.compiled("\\b" + _regex_escaped(class_name_declared) + "\\b")
+	var target: Dictionary = {
+		"path": resource_path, "uid": str(ResourceFiles.uid_of(resource_path).get("uid", ""))
+	}
 
-	var all_files: Array[String] = []
-	for ext: Variant in file_types:
-		all_files.append_array(_files.find_files("res://", "." + str(ext)))
+	var all_files: Array[String] = _usage_files(file_types)
 
 	var usages: Array[Dictionary] = []
 	var by_kind: Dictionary = {}
@@ -131,20 +139,29 @@ func find_resource_usages(params: Dictionary) -> Dictionary:
 	var in_code: int = 0
 
 	for file_path: String in all_files:
-		if file_path == resource_path:
+		# Its own sidecar names it as the file it was imported from, which is not a use of it.
+		if file_path == resource_path or file_path == resource_path + ".import":
 			continue
 		var file: FileAccess = FileAccess.open(file_path, FileAccess.READ)
 		if not file:
 			continue
 		var lines: PackedStringArray = file.get_as_text().split("\n")
 		file.close()
+		# A class is used by name only in code. In a scene or a resource the same word is a node's
+		# name or a caption, and each was counted as a use of the class.
+		var code: bool = file_path.get_extension() in ["gd", "gdshader"]
 
 		var references: Array[Dictionary] = []
 		for i: int in range(lines.size()):
 			var line: String = lines[i]
-			var by_its_path: bool = by_path.search(line) != null
-			var by_its_name: bool = not by_its_path and by_class != null and by_class.search(line) != null
-			if not by_its_path and not by_its_name:
+			var by_its_path: bool = _names_target(line, file_path, target)
+			var by_its_name: bool = false
+			var name_in_comment: bool = false
+			if not by_its_path and code and by_class != null:
+				# Strings are text, so a class named in one is not a use of it.
+				by_its_name = by_class.search(_code_of(line)) != null
+				name_in_comment = not by_its_name and by_class.search(_comment_of(line)) != null
+			if not by_its_path and not by_its_name and not name_in_comment:
 				continue
 			var trimmed: String = line.strip_edges()
 			var kind: String = ""
@@ -154,12 +171,12 @@ func find_resource_usages(params: Dictionary) -> Dictionary:
 			# three of them prose, all counted as code. The more carefully a project is documented
 			# the worse that ratio gets. `##` and `#` are kept apart because renaming the class
 			# breaks Godot's generated documentation and leaves the prose merely stale.
-			if trimmed.begins_with("##"):
+			if code and trimmed.begins_with("##"):
 				kind = "doc"
-			elif trimmed.begins_with("#"):
+			elif (code and trimmed.begins_with("#")) or name_in_comment:
 				kind = "comment"
 			elif by_its_path:
-				kind = _path_reference_kind(line)
+				kind = _path_reference_kind(line, file_path)
 			else:
 				kind = (
 					"extends" if Patterns.without_annotations(line).begins_with("extends ") else "class_name"
@@ -210,8 +227,81 @@ func _declared_class_name(path: String) -> String:
 	return ""
 
 
+# The files a reverse search reads, for the kinds asked for. The settings files are kinds of their
+# own because what they name is used as surely as a preload is: an autoload script, the main scene
+# and a plugin's script are named only in project.godot and plugin.cfg, and a search that left those
+# out answered that each was used by nothing, which is the answer a caller deletes a file on.
+func _usage_files(kinds: Array) -> Array[String]:
+	var found: Array[String] = []
+	for kind: Variant in kinds:
+		match str(kind):
+			"godot":
+				found.append("res://project.godot")
+			"cfg":
+				found.append_array(_files.find_files("res://", "plugin.cfg"))
+				if FileAccess.file_exists("res://export_presets.cfg"):
+					found.append("res://export_presets.cfg")
+			_:
+				found.append_array(_files.find_files("res://", "." + str(kind)))
+	return found
+
+
+# Whether [param line], in [param file_path], names the target by path or by UID. Every string on the
+# line is read as a path the way the engine reads it: a res:// path as it is, a uid:// by what it
+# names, and anything else relative to the file it is in, which is how `preload("sibling.gd")` and a
+# plugin.cfg's `script="plugin.gd"` name their files. Only the quoted form of the project path was
+# looked for, so neither of those was found, and nor was a scene named by its UID.
+func _names_target(line: String, file_path: String, target: Dictionary) -> bool:
+	var path: String = target["path"]
+	var uid: String = target["uid"]
+	for quoted: String in _string_literals(line):
+		# An autoload is written "*res://path" when its name is global.
+		var literal: String = quoted.trim_prefix("*")
+		if not uid.is_empty() and literal == uid:
+			return true
+		if literal.get_extension() != path.get_extension():
+			continue
+		var resolved: String = literal
+		if not literal.begins_with("res://"):
+			resolved = file_path.get_base_dir().path_join(literal).simplify_path()
+		if resolved == path:
+			return true
+	return false
+
+
+# The contents of each string literal on [param line], of either quote.
+static func _string_literals(line: String) -> Array[String]:
+	var literals: Array[String] = []
+	for m: RegExMatch in Patterns.compiled(STRING_LITERAL).search_all(line):
+		literals.append(m.get_string(1) if not m.get_string(1).is_empty() else m.get_string(2))
+	return literals
+
+
+# [param line] with its strings emptied and its comment taken off: the part a class can be used in.
+static func _code_of(line: String) -> String:
+	var bare: String = Patterns.compiled(STRING_LITERAL).sub(line, '""', true)
+	var mark: int = bare.find("#")
+	return bare if mark == -1 else bare.substr(0, mark)
+
+
+# The comment on [param line], strings emptied first so a # inside one does not start it.
+static func _comment_of(line: String) -> String:
+	var bare: String = Patterns.compiled(STRING_LITERAL).sub(line, '""', true)
+	var mark: int = bare.find("#")
+	return "" if mark == -1 else bare.substr(mark)
+
+
 # How a line that names the resource by path uses it.
-func _path_reference_kind(line: String) -> String:
+func _path_reference_kind(line: String, file_path: String) -> String:
+	match file_path.get_file():
+		"project.godot":
+			return "setting"
+		"plugin.cfg":
+			return "plugin"
+		"export_presets.cfg":
+			return "export_preset"
+	if file_path.ends_with(".import"):
+		return "import"
 	var trimmed: String = Patterns.without_annotations(line)
 	if trimmed.begins_with("extends "):
 		return "extends"
@@ -255,9 +345,15 @@ func _analyze_resource(path: String, current_depth: int, walk: DependencyWalk) -
 			walk.circular_references.append(cycle)
 		return [{"path": path, "circular": true}]
 
+	# Reused only when it was walked with as much depth left as now. A resource first reached deep in
+	# the walk has a list cut short at the limit, and handing that to a nearer reach answered with a
+	# chain that stopped where nothing stopped it.
+	var remaining: int = walk.max_depth - current_depth
 	if walk.visited.has(path):
-		var cached: Array[Dictionary] = walk.visited[path]
-		return cached
+		var cached: Dictionary = walk.visited[path]
+		if Read.as_int(cached["remaining"]) == remaining:
+			var cached_deps: Array[Dictionary] = cached["deps"]
+			return cached_deps
 
 	walk.path_stack.append(path)
 
@@ -269,7 +365,7 @@ func _analyze_resource(path: String, current_depth: int, walk: DependencyWalk) -
 		for pattern: String in REFERENCE_PATTERNS:
 			var regex: RegEx = Patterns.compiled(pattern)
 			for m: RegExMatch in regex.search_all(content):
-				var dep_path: String = _referenced_path(m.get_string())
+				var dep_path: String = _resolved(_referenced_path(m.get_string()), path)
 
 				if not dep_path.begins_with("res://"):
 					continue
@@ -299,10 +395,25 @@ func _analyze_resource(path: String, current_depth: int, walk: DependencyWalk) -
 					deps.append(dep_info)
 
 	walk.path_stack.pop_back()
-	walk.visited[path] = deps
+	walk.visited[path] = {"deps": deps, "remaining": remaining}
 	return deps
 
 
+# [param written] as the res:// path the engine would load from [param from]: a uid:// by what the
+# project's uid cache says it names, and a relative path against the referring file's directory.
+# Both were passed over as not being res:// paths, so a script's `preload("sibling.gd")` was no
+# dependency at all.
+static func _resolved(written: String, from: String) -> String:
+	if written.begins_with("res://"):
+		return written
+	if written.begins_with("uid://"):
+		var id: int = ResourceUID.text_to_id(written)
+		return ResourceUID.get_id_path(id) if ResourceUID.has_id(id) else written
+	if written.contains("://"):
+		return written
+	return from.get_base_dir().path_join(written).simplify_path()
+
+
 # The path inside a preload(), load() or ext_resource match; a bare res:// match is the path.
 func _referenced_path(matched: String) -> String:
 	var expression: String = ""

package/build/godot/operations/file_walk.gd

@@ -10,6 +10,26 @@ extends RefCounted
 # every caller files the engine will never answer for.
 
 
+# Why [param path], a res:// or uid:// path a setting names, is not a file the engine can load, or
+# empty when it is. A uid:// path resolves through the project's uid cache, which the import writes,
+# so one that does not resolve is a file that has gone or a project not imported yet, and saying
+# only that the file does not exist sent a caller looking for a scene that was there.
+static func missing_reason(path: String) -> String:
+	if path.begins_with("uid://"):
+		var id: int = ResourceUID.text_to_id(path)
+		if id == ResourceUID.INVALID_ID or not ResourceUID.has_id(id):
+			return (
+				path
+				+ " does not resolve: no file in the project's uid cache has it, so the file has gone or the"
+				+ " project has not been imported yet (project_import refresh_uids imports it)"
+			)
+		var resolved: String = ResourceUID.get_id_path(id)
+		return (
+			"" if FileAccess.file_exists(resolved) else path + " names " + resolved + ", which does not exist"
+		)
+	return "" if FileAccess.file_exists(path) else path + " does not exist"
+
+
 # A directory the engine steps over, marker file and all.
 func is_stepped_over(path: String) -> bool:
 	return FileAccess.file_exists(path + ".gdignore")