gdharness 1.2.40 → 1.2.42

package/build/godot/addons/gdharness_editor/scene_file.gd

@@ -30,13 +30,27 @@ const HeadlessCheck = preload("headless_check.gd")
 ## How many times what scripts changed is put back before a write is refused for it.
 const PUTTING_BACK_PASSES: int = 4
 const PropertyValues = preload("property_values.gd")
+const Read = preload("reading.gd")
+## The names Object.ConnectFlags gives each bit. The number alone left a reader guessing that 2 is
+## the persistence every connection in a saved scene carries.
+const CONNECT_FLAG_NAMES: Dictionary[int, String] = {
+	Object.CONNECT_DEFERRED: "deferred",
+	Object.CONNECT_PERSIST: "persist",
+	Object.CONNECT_ONE_SHOT: "one_shot",
+	Object.CONNECT_REFERENCE_COUNTED: "reference_counted",
+	Object.CONNECT_APPEND_SOURCE_OBJECT: "append_source_object",
+}
 
 ## Whether a scan asked for through [method scan_later] is still to start, which a caller waiting
 ## for the editor's files to settle has to wait through as well.
 static var scan_due: bool = false
+## The files a headless save named by path alone because the uid cache holds no uid for them,
+## gathered for the answer to the call that saved, the one call its engine runs.
+static var by_path: PackedStringArray = []
 
 var root: Node = null
 var path: String = ""
+## The path of each node a scene this one inherits gives, with the file that makes it.
 var _base_paths: Dictionary = {}
 var _state: SceneState = null
 ## What the file stores on each node it was opened with, by the node's instance id, so a node keeps
@@ -77,9 +91,16 @@ func open(scene_path: String, for_writing: bool) -> Dictionary:
 		return {"ok": false, "error": "Failed to instantiate " + path}
 	_state = packed.get_state()
 	var base: SceneState = _state.get_base_scene_state()
+	# Each node a base gives, with the file that makes it: the deepest base listing it as more than
+	# values set on a node from further down.
 	while base != null:
 		for index: int in base.get_node_count():
-			_base_paths[_relative(str(base.get_node_path(index)))] = true
+			var given: String = _relative(str(base.get_node_path(index)))
+			var made: bool = (
+				base.get_node_instance(index) != null or not str(base.get_node_type(index)).is_empty()
+			)
+			if made or not _base_paths.has(given):
+				_base_paths[given] = base.get_path()
 		base = base.get_base_scene_state()
 	# On a read as well, which would otherwise answer what the scripts set as what the file holds.
 	if not Engine.is_editor_hint():
@@ -122,6 +143,13 @@ func asked(node: Node, names: Array) -> void:
 		_reached.merge(HeadlessCheck.reached(node, property))
 
 
+## Takes [param resource], built into the scene, as one the tool changed, which a write saves as it is.
+func reached_into(resource: Resource) -> void:
+	var id: String = resource.get_scene_unique_id()
+	if not id.is_empty():
+		_reached[id] = true
+
+
 ## Takes each copy in [param copies], keyed by the node it was made from, as holding what that node's
 ## file entry holds.
 func copied(copies: Dictionary) -> void:
@@ -150,12 +178,74 @@ func refuse(error: String) -> Dictionary:
 	return {"ok": false, "error": error}
 
 
+## Each bit set in [param flags], a connection's, by name, and whatever bits are left unnamed as one
+## number.
+static func flag_names(flags: int) -> Array[String]:
+	var names: Array[String] = []
+	var rest: int = flags
+	for bit: int in CONNECT_FLAG_NAMES:
+		if flags & bit:
+			names.append(CONNECT_FLAG_NAMES[bit])
+			rest &= ~bit
+	if rest != 0:
+		names.append(str(rest))
+	return names
+
+
+## [param said], the refusal for [param node_path] found nowhere in this scene, with how a path is
+## read when it starts with the root's own name, and otherwise with the last node of the path the
+## scene has and what is under it, as after a node was moved or renamed.
+func not_found(said: String, node_path: String) -> String:
+	if root == null:
+		return said
+	if not root.has_node(NodePath(node_path.get_slice("/", 0))):
+		var hinted: String = Read.from_the_root(said, node_path, str(root.name))
+		if hinted != said:
+			return hinted
+	var parts: PackedStringArray = node_path.trim_prefix("./").split("/", false)
+	var at: Node = root
+	var reached: PackedStringArray = []
+	for part: String in parts:
+		var below: Node = at.get_node_or_null(NodePath(part))
+		if below == null:
+			break
+		at = below
+		var _walked: bool = reached.append(part)
+	if reached.size() >= parts.size():
+		return said
+	var names: PackedStringArray = []
+	for child: Node in at.get_children():
+		var _named: bool = names.append(str(child.name))
+	return Read.missing_below(said, str(root.name), reached, parts[reached.size()], names)
+
+
 func close() -> void:
 	if root != null:
 		root.free()
 		root = null
 
 
+## What the file holds under the instance at [param at] that goes once its children are not
+## editable, as {values, nodes}: the paths of the instance's nodes it sets values on, which stay with
+## the instance's own values, and of the nodes the scene added below one of them, which are gone,
+## since the packer skips everything below a node of an instance that is not editable. A node added
+## straight under [param at] is the scene's own and stays.
+func held_under(at: String) -> Dictionary:
+	var values: Array[String] = []
+	var nodes: Array[String] = []
+	for index: int in _state.get_node_count():
+		var entry: String = _relative(str(_state.get_node_path(index)))
+		var parent: String = _relative(str(_state.get_node_path(index, true)))
+		var values_only: bool = (
+			_state.get_node_instance(index) == null and str(_state.get_node_type(index)).is_empty()
+		)
+		if values_only and entry.begins_with(at + "/"):
+			values.append(entry)
+		elif not values_only and parent.begins_with(at + "/"):
+			nodes.append(entry)
+	return {"values": values, "nodes": nodes}
+
+
 ## The path of [param node] as a tool names it: "." for the root.
 func path_of(node: Node) -> String:
 	return str(root.get_path_to(node))
@@ -166,16 +256,46 @@ func path_of(node: Node) -> String:
 func foreign(node: Node) -> String:
 	if node == root or node.owner == root:
 		return ""
-	if node.owner != null and root.is_editable_instance(node.owner):
+	if node.owner == null:
+		return (
+			"%s is made by a script as the scene is instanced, and no scene file saves anything about it."
+			% path_of(node)
+		)
+	if root.is_editable_instance(node.owner):
 		return ""
-	var owner_path: String = path_of(node.owner) if node.owner != null else "?"
-	return (
+	var said: String = (
 		(
 			"%s belongs to the scene instanced at %s (%s), and this scene saves nothing about it. Edit "
-			+ "that scene instead."
+			+ "that scene instead, which changes every instance of it"
 		)
-		% [path_of(node), owner_path, node.owner.scene_file_path if node.owner != null else "?"]
+		% [path_of(node), path_of(node.owner), node.owner.scene_file_path]
 	)
+	var steps: PackedStringArray = []
+	for closed: String in _closed_around(node):
+		var _added: bool = steps.append("nodePath %s editableChildren true" % closed)
+	if steps.is_empty():
+		return said + "."
+	return (
+		said
+		+ ", or have this scene keep its own values for this instance with scene_node set "
+		+ ", then ".join(steps)
+		+ "."
+	)
+
+
+## The instances around [param node] whose children are not editable, outermost first: each must be
+## made editable, in that order, before this scene keeps values of its own for [param node], since
+## the packer skips every node under an instance that is not. Empty when nothing would let it.
+func _closed_around(node: Node) -> PackedStringArray:
+	var closed: PackedStringArray = []
+	var instance: Node = node.owner
+	while instance != root:
+		if instance == null:
+			return []
+		if not root.is_editable_instance(instance):
+			var _at: int = closed.insert(0, path_of(instance))
+		instance = instance.owner
+	return closed
 
 
 ## Why [param node] cannot be moved, renamed, copied or deleted, or "": the scene may only
@@ -192,10 +312,10 @@ func fixed(node: Node) -> String:
 	if _base_paths.has(at):
 		return (
 			(
-				"%s comes from the scene %s inherits from, which creates it again on load. Edit that "
+				"%s is made by %s, a scene %s inherits, which creates it again on load. Edit that "
 				+ "scene instead."
 			)
-			% [at, path]
+			% [at, _base_paths[at], path]
 		)
 	return ""
 
@@ -323,10 +443,25 @@ func unusable_name(parent: Node, child_name: String, moving: Node = null) -> Str
 
 ## The names of the properties this scene's own file sets on [param node], whatever their values.
 func set_here(node: Node) -> Dictionary:
+	return set_at(path_of(node))
+
+
+## Where the values of [param node], at [param at] in the file, come from when the file does not set
+## them: "" for a node this scene makes, which holds them all, or the scene that makes the node, the
+## one it is instanced from or one this scene inherits.
+func values_from(node: Node, at: String) -> String:
+	if node != root and not node.scene_file_path.is_empty():
+		return node.scene_file_path
+	if node != root and node.owner != root:
+		return node.owner.scene_file_path if node.owner != null else ""
+	return str(_base_paths.get(at, ""))
+
+
+## The names of the properties this scene's own file sets on the node at [param at].
+func set_at(at: String) -> Dictionary:
 	var names: Dictionary = {}
 	if _state == null:
 		return names
-	var at: String = path_of(node)
 	for index: int in _state.get_node_count():
 		if _relative(str(_state.get_node_path(index))) != at:
 			continue
@@ -438,17 +573,85 @@ static func save_packed(packed: PackedScene, scene_path: String) -> Dictionary:
 static func save_keeping_uid(resource: Resource, file_path: String) -> Error:
 	if Engine.is_editor_hint():
 		return ResourceSaver.save(resource, file_path)
-	var uid: int = _uid_in(file_path)
+	var uid: int = uid_in(file_path)
 	var saving: Error = ResourceSaver.save(resource, file_path)
 	if saving != OK:
 		return saving
 	if uid == ResourceUID.INVALID_ID:
 		uid = ResourceUID.create_id()
-	return ResourceSaver.set_uid(file_path, uid)
+	var marked: Error = ResourceSaver.set_uid(file_path, uid)
+	if marked != OK:
+		return marked
+	return _with_external_uids(file_path)
+
+
+## Puts back the uid on each external resource the text file at [param file_path] names. Only the
+## editor's file system tells the saver a path's uid, so a headless save writes every reference by
+## path alone, and each breaks when the file it names is moved.
+static func _with_external_uids(file_path: String) -> Error:
+	if not (file_path.ends_with(".tscn") or file_path.ends_with(".tres")):
+		return OK
+	var lines: PackedStringArray = FileAccess.get_file_as_string(file_path).split("\n")
+	var pattern: RegEx = RegEx.create_from_string(' path="([^"]+)"')
+	var changed: bool = false
+	for at: int in lines.size():
+		var line: String = lines[at]
+		if not line.begins_with("[ext_resource ") or line.contains(' uid="'):
+			continue
+		var named: RegExMatch = pattern.search(line)
+		if named == null:
+			continue
+		var uid: String = reference_uid(named.get_string(1))
+		if not uid.is_empty():
+			lines[at] = line.replace(' path="', uid + ' path="')
+			changed = true
+	if not changed:
+		return OK
+	var file: FileAccess = FileAccess.open(file_path, FileAccess.WRITE)
+	if file == null:
+		return FileAccess.get_open_error()
+	if not file.store_string("\n".join(lines)):
+		return ERR_FILE_CANT_WRITE
+	file.close()
+	return OK
+
+
+## [method uid_attribute] for a reference about to be written, noting [param named] under
+## [member by_path] when it is left to be named by path.
+static func reference_uid(named: String) -> String:
+	var uid: String = uid_attribute(named)
+	if uid.is_empty():
+		note_by_path(named)
+	return uid
+
+
+## Notes [param named], a reference just written by path alone, under [member by_path] when the uid
+## cache holds nothing for it: a file made since the project was last scanned, whose uid the cache
+## learns from the next scan. Not a file whose uid the cache gives to another, which a scan leaves.
+static func note_by_path(named: String) -> void:
+	if Engine.is_editor_hint() or not FileAccess.file_exists(named) or by_path.has(named):
+		return
+	var own: int = uid_in(named)
+	if own == ResourceUID.INVALID_ID and FileAccess.file_exists(named + ".uid"):
+		own = ResourceUID.text_to_id(FileAccess.get_file_as_string(named + ".uid").strip_edges())
+	if own == ResourceUID.INVALID_ID or not ResourceUID.has_id(own):
+		var _noted: bool = by_path.append(named)
+
+
+## The uid attribute a reference to [param named] is written with, as ' uid="uid://..."', or "".
+##
+## Only a uid the uid cache gives that path, which is what the loader resolves it by. A uid the cache
+## does not know (a file made with no editor since the last scan) is answered with a warning on every
+## load, and one it gives another file (a scene copied whole keeps its original's) loads that file.
+static func uid_attribute(named: String) -> String:
+	var id: int = ResourceLoader.get_resource_uid(named)
+	if id == ResourceUID.INVALID_ID or not ResourceUID.has_id(id) or ResourceUID.get_id_path(id) != named:
+		return ""
+	return ' uid="%s"' % ResourceUID.id_to_text(id)
 
 
 ## The uid the file at [param file_path] declares, or [constant ResourceUID.INVALID_ID].
-static func _uid_in(file_path: String) -> int:
+static func uid_in(file_path: String) -> int:
 	if not FileAccess.file_exists(file_path):
 		return ResourceUID.INVALID_ID
 	var file: FileAccess = FileAccess.open(file_path, FileAccess.READ)

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

@@ -664,8 +664,12 @@ func _serialize_array(value: Array) -> Array:
 
 # Base64 rather than a list of numbers. A byte array is a texture, a sound or a save file often
 # enough that the list would be the whole answer, megabytes of it, and unreadable either way.
+#
+# The engine's encoder raises an error on an empty array, and an empty tile_map_data is every
+# TileMapLayer with nothing painted yet, so a read of one carried an engine error in its answer.
 func _serialize_bytes(value: PackedByteArray) -> Dictionary:
-	return {"base64": Marshalls.raw_to_base64(value), "size": value.size(), "_type": "PackedByteArray"}
+	var text: String = "" if value.is_empty() else Marshalls.raw_to_base64(value)
+	return {"base64": text, "size": value.size(), "_type": "PackedByteArray"}
 
 
 # The packed vector and colour arrays, each element serialised the way one of them on its own is.

package/build/godot/addons/gdharness_editor/tools/animation_tools.gd

@@ -1,9 +1,11 @@
 @tool
 extends Node
 
-## Animations and animation trees, edited in the open editor.
+## Animations and animation trees, edited in the open editor or, for a project no editor serves, by a
+## headless engine.
 
 const AnimationReads = preload("../animation_reads.gd")
+const HeadlessCheck = preload("../headless_check.gd")
 const PropertyValues = preload("../property_values.gd")
 const Read = preload("../reading.gd")
 const SceneFile = preload("../scene_file.gd")
@@ -46,7 +48,9 @@ func _open_at(scene_path: String, node_path: String, kind: String) -> Array:
 		return [scene, null, refused]
 	var node: Node = _find_node(scene.root, node_path)
 	if node == null or not node.is_class(kind):
-		return [scene, null, scene.refuse("%s not found at: %s" % [kind, node_path])]
+		return [
+			scene, null, scene.refuse(scene.not_found("%s not found at: %s" % [kind, node_path], node_path))
+		]
 	var foreign: String = scene.foreign(node)
 	if not foreign.is_empty():
 		return [scene, null, scene.refuse(foreign)]
@@ -62,25 +66,55 @@ func _read_at(scene_path: String, node_path: String, kind: String) -> Array:
 		return [scene, null, refused]
 	var node: Node = _find_node(scene.root, node_path)
 	if node == null or not node.is_class(kind):
-		return [scene, null, scene.refuse("%s not found at: %s" % [kind, node_path])]
+		return [
+			scene, null, scene.refuse(scene.not_found("%s not found at: %s" % [kind, node_path], node_path))
+		]
 	return [scene, node, {}]
 
 
 ## Writes [param scene] once [param check] passes, then the files of [param homes], answering
 ## [param answer] or a refusal.
 func _finish(scene: SceneFile, check: Callable, homes: Dictionary, answer: Dictionary) -> Dictionary:
+	if not Engine.is_editor_hint():
+		for file: Variant in homes:
+			var home: Resource = homes[file]
+			if _scripted(home):
+				return (
+					scene
+					. refuse(
+						(
+							(
+								(
+									"Nothing was written: %s holds a resource with a script that is not a tool, and what "
+									+ "that script changed when a headless engine loaded it cannot be told apart from the "
+									+ "edit. "
+								)
+								% file
+							)
+							+ HeadlessCheck.REMEDY
+						)
+					)
+				)
 	var written: Dictionary = scene.write(check)
 	if not written.is_empty():
 		return written
 	for file: Variant in homes:
 		var resource: Resource = homes[file]
-		var saving: Error = ResourceSaver.save(resource, str(file))
+		var saving: Error = SceneFile.save_keeping_uid(resource, str(file))
 		if saving != OK:
 			return {"ok": false, "error": "Failed to save %s: %s" % [file, error_string(saving)]}
-		EditorInterface.get_resource_filesystem().update_file(str(file))
+		if Engine.is_editor_hint():
+			EditorInterface.get_resource_filesystem().update_file(str(file))
 	return answer
 
 
+## Whether [param resource], or one it embeds, has a script that is not a tool, which a headless
+## engine ran as it loaded the file.
+func _scripted(resource: Resource) -> bool:
+	var script: Script = resource.get_script()
+	return (script != null and not script.is_tool()) or HeadlessCheck.holds_scripted_embedded(resource, {})
+
+
 func _parse_json_maybe(value: Variant) -> Variant:
 	if typeof(value) != TYPE_STRING:
 		return value

package/build/godot/addons/gdharness_editor/tools/resource_tools.gd

@@ -399,6 +399,19 @@ func _atlas(entry: Variant, index: int) -> Array:
 	if texture_path.split("/").has(".."):
 		return [false, "sources[%d].texture leaves the project: %s" % [index, texture_path]]
 	if not ResourceLoader.exists(texture_path):
+		# An image the engine has not imported loads as nothing, where "no texture" would send a caller
+		# looking for a file that is there.
+		if FileAccess.file_exists(texture_path) and not FileAccess.file_exists(texture_path + ".import"):
+			return [
+				false,
+				(
+					(
+						"sources[%d].texture: %s has not been imported, so the engine has no texture for it "
+						+ "yet. project_import reimport with resourcePath %s imports it."
+					)
+					% [index, texture_path, texture_path]
+				)
+			]
 		return [false, "sources[%d].texture: no texture at %s" % [index, texture_path]]
 	var texture: Texture2D = load(texture_path) as Texture2D
 	if texture == null:
@@ -720,13 +733,15 @@ func set_theme_color(args: Dictionary) -> Dictionary:
 		return {"ok": false, "error": "The theme saved without %s/%s" % [control_type, color_name]}
 
 	var stored: Color = saved.get_color(color_name, control_type)
-	return {
-		"ok": true,
-		"themePath": theme_path,
-		"controlType": control_type,
-		"colorName": color_name,
-		"color": {"r": stored.r, "g": stored.g, "b": stored.b, "a": stored.a}
-	}
+	return _noting_variation(
+		{
+			"ok": true,
+			"themePath": theme_path,
+			"controlType": control_type,
+			"colorName": color_name,
+			"color": {"r": stored.r, "g": stored.g, "b": stored.b, "a": stored.a}
+		}
+	)
 
 
 func set_theme_font_size(args: Dictionary) -> Dictionary:
@@ -743,7 +758,23 @@ func set_theme_font_size(args: Dictionary) -> Dictionary:
 	if theme == null:
 		return {"ok": false, "error": "No Theme at %s. Create one there first." % theme_path}
 
-	theme.set_font_size(font_size_name, control_type, Read.as_int(args.get("size", 0)))
+	# Godot reads a size of 0 or less as unset and answers the theme's default, so -3 would be read
+	# back as 16.
+	var pixels: float = Read.as_float(args.get("size"), 0.0)
+	if not is_finite(pixels) or pixels < 1 or pixels != floorf(pixels):
+		var shown: String = str(int(pixels)) if pixels == floorf(pixels) else str(pixels)
+		return {
+			"ok": false,
+			"error":
+			(
+				(
+					"size must be a whole number of pixels, 1 or more, not %s: Godot reads 0 or less as no size "
+					% shown
+				)
+				+ "and uses the theme's default instead."
+			)
+		}
+	theme.set_font_size(font_size_name, control_type, int(pixels))
 
 	var unsaved: String = _save_theme(theme, theme_path, "%s/font_sizes/%s" % [control_type, font_size_name])
 	if not unsaved.is_empty():
@@ -753,10 +784,32 @@ func set_theme_font_size(args: Dictionary) -> Dictionary:
 	if saved == null or not saved.has_font_size(font_size_name, control_type):
 		return {"ok": false, "error": "The theme saved without %s/%s" % [control_type, font_size_name]}
 
-	return {
-		"ok": true,
-		"themePath": theme_path,
-		"controlType": control_type,
-		"fontSizeName": font_size_name,
-		"size": saved.get_font_size(font_size_name, control_type)
-	}
+	return _noting_variation(
+		{
+			"ok": true,
+			"themePath": theme_path,
+			"controlType": control_type,
+			"fontSizeName": font_size_name,
+			"size": saved.get_font_size(font_size_name, control_type)
+		}
+	)
+
+
+## [param answer] with a note when its controlType names no class a theme styles. Any name is a
+## theme type, so one that is no class is a type variation, which styles only a control whose
+## theme_type_variation names it, and a misspelt "Buton" would otherwise read as Button set.
+func _noting_variation(answer: Dictionary) -> Dictionary:
+	var type: String = str(answer.get("controlType", ""))
+	if (
+		ClassDB.class_exists(type)
+		and (ClassDB.is_parent_class(type, "Control") or ClassDB.is_parent_class(type, "Window"))
+	):
+		return answer
+	answer["note"] = (
+		(
+			"%s is not a Control or Window class, so this is a type variation: it styles only a control "
+			+ "whose theme_type_variation is %s."
+		)
+		% [type, type]
+	)
+	return answer