gdharness 1.2.40 → 1.2.42

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

@@ -5,22 +5,14 @@ extends Node
 
 const FileReads = preload("../file_reads.gd")
 const Read = preload("../reading.gd")
+const Kin = preload("scene_kin.gd")
+const Paths = preload("scene_paths.gd")
 const Placing = preload("scene_placing.gd")
 const PropertyValues = preload("../property_values.gd")
 const ResourceTools = preload("resource_tools.gd")
 const SceneFile = preload("../scene_file.gd")
 const Serialisation = preload("../serialisation.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",
-}
-
 var _editor_plugin: EditorPlugin = null
 var _values: Serialisation = Serialisation.new()
 var _properties: PropertyValues = PropertyValues.new()
@@ -30,19 +22,6 @@ func set_editor_plugin(plugin: EditorPlugin) -> void:
 	_editor_plugin = plugin
 
 
-## Each bit set in [param flags] 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
-
-
 func _ensure_res_path(path: String) -> String:
 	if not path.begins_with("res://"):
 		return "res://" + path
@@ -111,7 +90,7 @@ func _kept(scene: SceneFile, saved: Node, node: Node, names: Array) -> String:
 					"%s.%s would load from the file as %s: the scene does not keep it, because the property "
 					+ "is not one a scene stores or the node belongs to another scene."
 				)
-				% [at, property, JSON.stringify(_values.serialize_value(loaded))]
+				% [at, property, JSON.stringify(_values.serialize_value(loaded), "", false)]
 			)
 	return ""
 
@@ -175,17 +154,42 @@ func _collect_nodes_recursive(node: Node, path: String, out_nodes: Array) -> voi
 		_collect_nodes_recursive(child, child_path, out_nodes)
 
 
+func _inherited(args: Dictionary) -> Dictionary:
+	var project_path: String = str(args.get("projectPath", ""))
+	var script_path: String = str(args.get("script", ""))
+	return Kin.inherited(
+		args,
+		_new_scene_path(args),
+		_to_scene_res_path(project_path, str(args.get("inherits", ""))),
+		"" if script_path.is_empty() else _to_scene_res_path(project_path, script_path)
+	)
+
+
+## The res:// path a create in [param args] writes, given .tscn when it has no extension, or "".
+func _new_scene_path(args: Dictionary) -> String:
+	var scene_path: String = _to_scene_res_path(
+		str(args.get("projectPath", "")), str(args.get("scenePath", ""))
+	)
+	if scene_path == "res://":
+		return ""
+	return scene_path if scene_path.ends_with(".tscn") else scene_path + ".tscn"
+
+
 func create_scene(args: Dictionary) -> Dictionary:
+	if str(args.get("inherits", "")).is_empty():
+		return _create_of_a_class(args)
+	return _inherited(args)
+
+
+func _create_of_a_class(args: Dictionary) -> Dictionary:
 	var project_path: String = str(args.get("projectPath", ""))
-	var scene_path: String = _to_scene_res_path(project_path, str(args.get("scenePath", "")))
+	var scene_path: String = _new_scene_path(args)
 	var root_node_type: String = str(args.get("rootNodeType", "Node"))
 	var root_node_name: String = str(args.get("rootNodeName", root_node_type))
 	var script_path: String = str(args.get("script", ""))
 
-	if scene_path == "res://":
+	if scene_path.is_empty():
 		return {"ok": false, "error": "Missing scenePath"}
-	if not scene_path.ends_with(".tscn"):
-		scene_path += ".tscn"
 	var asked_type: String = root_node_type
 	var made: Dictionary = SceneFile.made_as(
 		root_node_type,
@@ -208,19 +212,8 @@ func create_scene(args: Dictionary) -> Dictionary:
 	var unfit: String = SceneFile.unfit_name(root_node_name)
 	if not unfit.is_empty():
 		return {"ok": false, "error": unfit}
-	# Saving over a scene that is there replaced it, nodes and all, and answered as a new scene.
 	if FileAccess.file_exists(scene_path):
-		return {
-			"ok": false,
-			"error":
-			(
-				(
-					"%s already exists, and scene_create op=create would replace everything in it. Edit it "
-					+ "with scene_node, or create the scene under another path."
-				)
-				% scene_path
-			)
-		}
+		return Kin.taken(scene_path)
 
 	var root: Node = ClassDB.instantiate(root_node_type)
 	root.name = root_node_name
@@ -312,7 +305,7 @@ func add_node(args: Dictionary) -> Dictionary:
 	var root: Node = scene.root
 	var parent: Node = _find_node(root, parent_node_path)
 	if not parent:
-		return scene.refuse("Parent node not found: " + parent_node_path)
+		return scene.refuse(scene.not_found("Parent node not found: " + parent_node_path, parent_node_path))
 	var foreign: String = scene.foreign(parent)
 	if not foreign.is_empty():
 		return scene.refuse(foreign)
@@ -387,7 +380,7 @@ func delete_node(args: Dictionary) -> Dictionary:
 
 	var node: Node = _find_node(scene.root, node_path)
 	if not node:
-		return scene.refuse("Node not found: " + node_path)
+		return scene.refuse(scene.not_found("Node not found: " + node_path, node_path))
 	var fixed: String = scene.fixed(node)
 	if not fixed.is_empty():
 		return scene.refuse(fixed)
@@ -395,6 +388,8 @@ func delete_node(args: Dictionary) -> Dictionary:
 	var at: String = scene.path_of(node)
 	node.get_parent().remove_child(node)
 	node.free()
+	var carried: Paths = Paths.new()
+	var _rewritten: int = carried.carry(scene, {at: ""})
 
 	var written: Dictionary = scene.write(
 		func(saved: Node) -> String:
@@ -405,7 +400,9 @@ func delete_node(args: Dictionary) -> Dictionary:
 	if not written.is_empty():
 		return written
 
-	return {"ok": true, "deletedNodePath": at}
+	var answer: Dictionary = {"ok": true, "deletedNodePath": at}
+	answer.merge(Kin.follow(scene_path, at, "", carried))
+	return answer
 
 
 func duplicate_node(args: Dictionary) -> Dictionary:
@@ -427,7 +424,7 @@ func duplicate_node(args: Dictionary) -> Dictionary:
 	var root: Node = scene.root
 	var source: Node = _find_node(root, node_path)
 	if not source:
-		return scene.refuse("Node not found: " + node_path)
+		return scene.refuse(scene.not_found("Node not found: " + node_path, node_path))
 	if source == root:
 		return scene.refuse("The root of %s cannot be copied into its own scene." % scene_path)
 	var foreign: String = scene.foreign(source)
@@ -438,7 +435,7 @@ func duplicate_node(args: Dictionary) -> Dictionary:
 	if not parent_path.is_empty():
 		target_parent = _find_node(root, parent_path)
 	if not target_parent:
-		return scene.refuse("Parent not found: " + parent_path)
+		return scene.refuse(scene.not_found("Parent not found: " + parent_path, parent_path))
 	foreign = scene.foreign(target_parent)
 	if not foreign.is_empty():
 		return scene.refuse(foreign)
@@ -458,6 +455,7 @@ func duplicate_node(args: Dictionary) -> Dictionary:
 	scene.copied(copies)
 
 	var new_path: String = scene.path_of(duplicated_node)
+	var placed: Array = [scene.path_of(target_parent), duplicated_node.get_index()]
 	var written: Dictionary = scene.write(
 		func(saved: Node) -> String:
 			if saved.get_node_or_null(new_path) == null:
@@ -467,7 +465,14 @@ func duplicate_node(args: Dictionary) -> Dictionary:
 	if not written.is_empty():
 		return written
 
-	return {"ok": true, "nodePath": node_path, "newName": new_name, "newNodePath": new_path}
+	return {
+		"ok": true,
+		"nodePath": node_path,
+		"newName": new_name,
+		"newNodePath": new_path,
+		"parentNodePath": placed[0],
+		"index": placed[1],
+	}
 
 
 func reparent_node(args: Dictionary) -> Dictionary:
@@ -491,9 +496,9 @@ func reparent_node(args: Dictionary) -> Dictionary:
 	var node: Node = _find_node(root, node_path)
 	var new_parent: Node = _find_node(root, new_parent_path)
 	if not node:
-		return scene.refuse("Node not found: " + node_path)
+		return scene.refuse(scene.not_found("Node not found: " + node_path, node_path))
 	if not new_parent:
-		return scene.refuse("New parent not found: " + new_parent_path)
+		return scene.refuse(scene.not_found("New parent not found: " + new_parent_path, new_parent_path))
 	var fixed: String = scene.fixed(node)
 	if not fixed.is_empty():
 		return scene.refuse(fixed)
@@ -525,6 +530,8 @@ func reparent_node(args: Dictionary) -> Dictionary:
 
 	var new_path: String = scene.path_of(node)
 	var index: int = node.get_index()
+	var carried: Paths = Paths.new()
+	var _rewritten: int = carried.carry(scene, {old_path: new_path} if new_path != old_path else {})
 	var written: Dictionary = scene.write(
 		func(saved: Node) -> String:
 			var copy: Node = saved.get_node_or_null(new_path)
@@ -537,15 +544,19 @@ func reparent_node(args: Dictionary) -> Dictionary:
 			return ""
 	)
 	if not written.is_empty():
+		carried.put_back(scene_path)
 		return written
 
-	return {
+	var answer: Dictionary = {
 		"ok": true,
 		"nodePath": old_path,
 		"newParentPath": new_parent_path,
 		"newNodePath": new_path,
 		"index": index,
 	}
+	if new_path != old_path:
+		answer.merge(Kin.follow(scene_path, old_path, new_path, carried))
+	return answer
 
 
 func set_node_properties(args: Dictionary) -> Dictionary:
@@ -553,6 +564,9 @@ func set_node_properties(args: Dictionary) -> Dictionary:
 	var scene_path: String = _to_scene_res_path(project_path, str(args.get("scenePath", "")))
 	var node_path: String = str(args.get("nodePath", "."))
 	var properties: Dictionary = _parse_properties_arg(args.get("properties", {}))
+	var editable: Variant = args.get("editableChildren")
+	if properties.is_empty() and editable == null:
+		return {"ok": false, "error": "set takes properties, editableChildren, or both."}
 
 	var opened: Array = _open(scene_path, true)
 	var scene: SceneFile = opened[0]
@@ -562,7 +576,7 @@ func set_node_properties(args: Dictionary) -> Dictionary:
 
 	var node: Node = _find_node(scene.root, node_path)
 	if not node:
-		return scene.refuse("Node not found: " + node_path)
+		return scene.refuse(scene.not_found("Node not found: " + node_path, node_path))
 	var foreign: String = scene.foreign(node)
 	if not foreign.is_empty():
 		return scene.refuse(foreign)
@@ -574,6 +588,15 @@ func set_node_properties(args: Dictionary) -> Dictionary:
 		if not unusable.is_empty():
 			return scene.refuse(unusable)
 
+	var dropped: Dictionary = {}
+	if editable != null:
+		var not_an_instance: String = Kin.set_editable(scene, node, Read.as_bool(editable))
+		if not not_an_instance.is_empty():
+			return scene.refuse(not_an_instance)
+		if not Read.as_bool(editable):
+			dropped = scene.held_under(scene.path_of(node))
+
+	var old_path: String = scene.path_of(node)
 	scene.asked(node, properties.keys())
 	var refused_property: String = _properties.write_all(node, properties)
 	if not refused_property.is_empty():
@@ -583,13 +606,29 @@ func set_node_properties(args: Dictionary) -> Dictionary:
 	for key: Variant in properties:
 		held[str(key)] = _readable(node, _properties.read_at(node, str(key)))
 	var new_path: String = scene.path_of(node)
+	var carried: Paths = Paths.new()
+	var _rewritten: int = carried.carry(scene, {old_path: new_path} if new_path != old_path else {})
 	var written: Dictionary = scene.write(
-		func(saved: Node) -> String: return _kept(scene, saved, node, properties.keys())
+		func(saved: Node) -> String:
+			var unkept: String = _kept(scene, saved, node, properties.keys())
+			if unkept.is_empty() and editable != null:
+				if saved.is_editable_instance(saved.get_node(new_path)) != Read.as_bool(editable):
+					return "%s would load with editableChildren %s." % [new_path, not Read.as_bool(editable)]
+			return unkept
 	)
 	if not written.is_empty():
+		carried.put_back(scene_path)
 		return written
 
-	return {"ok": true, "nodePath": new_path, "properties": held}
+	var answer: Dictionary = {"ok": true, "nodePath": new_path, "properties": held}
+	if editable != null:
+		answer["editableChildren"] = Read.as_bool(editable)
+	if not dropped.is_empty():
+		answer["droppedValues"] = dropped["values"]
+		answer["droppedNodes"] = dropped["nodes"]
+	if new_path != old_path:
+		answer.merge(Kin.follow(scene_path, old_path, new_path, carried))
+	return answer
 
 
 func get_node_properties(args: Dictionary) -> Dictionary:
@@ -606,7 +645,7 @@ func get_node_properties(args: Dictionary) -> Dictionary:
 
 	var node: Node = _find_node(scene.root, node_path)
 	if not node:
-		return scene.refuse("Node not found: " + node_path)
+		return scene.refuse(scene.not_found("Node not found: " + node_path, node_path))
 
 	# Against the default the node would have in no scene: its script's for what the script
 	# declares, the class's for the rest. Compared with a bare instance of the class, every exported
@@ -614,8 +653,11 @@ func get_node_properties(args: Dictionary) -> Dictionary:
 	# names this scene's file sets are always answered.
 	var props: Dictionary = _properties_of(node, include_defaults, scene.set_here(node))
 	var cells: Dictionary = ResourceTools.cells_of(node)
-	scene.close()
 	var answer: Dictionary = {"ok": true, "nodePath": node_path, "properties": props}
+	if node != scene.root and node.owner != null and not node.scene_file_path.is_empty():
+		answer["instanceOf"] = node.scene_file_path
+		answer["editableChildren"] = scene.root.is_editable_instance(node)
+	scene.close()
 	# Only an editor holds anything unsaved; a headless engine answering false would say it looked.
 	if Engine.is_editor_hint():
 		answer["unsavedInEditor"] = SceneFile.unsaved(scene_path)
@@ -770,7 +812,7 @@ func connect_signal(args: Dictionary) -> Dictionary:
 		"targetNodePath": to,
 		"methodName": method_name,
 		"flags": saved_flags[0],
-		"flagNames": _flag_names(Read.as_int(saved_flags[0])),
+		"flagNames": SceneFile.flag_names(Read.as_int(saved_flags[0])),
 		# Connected either way, as the editor's own dialog allows, since the method may be written
 		# next; a caller told nothing learnt of a misspelt one only when the signal fired.
 		"methodFound": method_found
@@ -781,7 +823,7 @@ func connect_signal(args: Dictionary) -> Dictionary:
 	if flags_before >= 0:
 		answer["alreadyConnected"] = true
 		if flags_before != Read.as_int(saved_flags[0]):
-			answer["flagsBefore"] = _flag_names(flags_before)
+			answer["flagsBefore"] = SceneFile.flag_names(flags_before)
 	return answer
 
 
@@ -792,9 +834,9 @@ func _connection_ends(
 	var source: Node = _find_node(scene.root, source_node_path)
 	var target: Node = _find_node(scene.root, target_node_path)
 	if not source:
-		return [null, "Source node not found: " + source_node_path]
+		return [null, scene.not_found("Source node not found: " + source_node_path, source_node_path)]
 	if not target:
-		return [null, "Target node not found: " + target_node_path]
+		return [null, scene.not_found("Target node not found: " + target_node_path, target_node_path)]
 	# pack drops a connection with either end inside an instanced scene, and the answer said it was
 	# made or removed.
 	for end: Node in [source, target]:
@@ -897,7 +939,7 @@ func list_connections(args: Dictionary) -> Dictionary:
 	if not filter_path.is_empty():
 		filtered = _find_node(root, filter_path)
 		if filtered == null:
-			return scene.refuse("Node not found: " + filter_path)
+			return scene.refuse(scene.not_found("Node not found: " + filter_path, filter_path))
 	var nodes: Array = []
 	_collect_nodes_recursive(root, ".", nodes)
 
@@ -934,7 +976,7 @@ func list_connections(args: Dictionary) -> Dictionary:
 							"targetNodePath": target_path,
 							"methodName": str(callable.get_method()),
 							"flags": flags,
-							"flagNames": _flag_names(flags),
+							"flagNames": SceneFile.flag_names(flags),
 							# False for a connection an instanced scene makes inside itself, which only that
 							# scene can change.
 							"editable": editable

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

@@ -22,6 +22,9 @@ extends RefCounted
 # number was expected. Absent keys never reach here: the callers pass their own default to
 # `Dictionary.get`, so what arrives is that default.
 
+## How many of a node's children a refusal for a path missing below it names.
+const NAMED_CHILDREN: int = 12
+
 
 static func as_int(value: Variant, fallback: int = 0) -> int:
 	if value is int:
@@ -99,3 +102,40 @@ static func json_or_null(text: String) -> Variant:
 	if json.parse(text) != OK:
 		return null
 	return json.data
+
+
+## [param said], the refusal for [param node_path] found nowhere in a scene whose root is called
+## [param root_name], with how paths are read when the path starts with that name and the root has
+## no child called that. Paths go from the root, so its own name there names a child of it, and a
+## caller who read the root as Main in a tree wrote Main/Body and was told only that nothing is there.
+static func from_the_root(said: String, node_path: String, root_name: String) -> String:
+	var first: String = node_path.get_slice("/", 0)
+	if root_name.is_empty() or first != root_name:
+		return said
+	var rest: String = node_path.substr(first.length() + 1)
+	var how: String = 'Paths go from the root, %s, whose own path is "."' % root_name
+	if not rest.is_empty():
+		how += ', so this one is "%s"' % rest
+	return "%s%s %s." % [said, "" if said.ends_with(".") else ".", how]
+
+
+## [param said], the refusal for a path a scene does not have, with where the path leaves it: the
+## last node of the path it has, [param reached] from the root, called [param root_name], when that
+## is empty; the name below it that is missing; and [param children], the names that node has, as
+## after a node was moved or renamed. Names up to [constant NAMED_CHILDREN] of them.
+static func missing_below(
+	said: String, root_name: String, reached: PackedStringArray, missing: String, children: PackedStringArray
+) -> String:
+	var shown: String = ", ".join(children.slice(0, NAMED_CHILDREN))
+	if children.size() > NAMED_CHILDREN:
+		shown += " and %d more" % (children.size() - NAMED_CHILDREN)
+	return (
+		"%s%s %s has no %s; %s."
+		% [
+			said,
+			"" if said.ends_with(".") else ".",
+			"The root, %s," % root_name if reached.is_empty() else "/".join(reached),
+			missing,
+			"its children are " + shown if not children.is_empty() else "it has no children",
+		]
+	)

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

@@ -660,7 +660,9 @@ static func _is_empty(owed: Variant) -> bool:
 ## taken the lot: see [member _outgoing].
 func _send_response(client: StreamPeerTCP, data: Dictionary) -> void:
 	var owed: PackedByteArray = _outgoing.get(client, PackedByteArray())
-	owed.append_array((JSON.stringify(data) + "\n").to_utf8_buffer())
+	# Keys left in the order they were put in: sorted, a map read came back in another order than
+	# its keys() and the game iterate it in.
+	owed.append_array((JSON.stringify(data, "", false) + "\n").to_utf8_buffer())
 	_outgoing[client] = owed
 
 

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

@@ -129,8 +129,8 @@ func set_property(params: Dictionary) -> Dictionary:
 				% [
 					reached["called"],
 					named,
-					JSON.stringify(_values.serialize(given)),
-					JSON.stringify(_values.serialize(now)),
+					JSON.stringify(_values.serialize(given), "", false),
+					JSON.stringify(_values.serialize(now), "", false),
 					why,
 				]
 			)

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

@@ -195,14 +195,19 @@ static func control_saying(root: Node, root_path: String, wanted: String, which:
 		}
 	var index: int = 0 if which == null else Read.as_int(which, -1)
 	if index < 0 or index >= targets.size():
-		var plural: String = "" if targets.size() == 1 else "s"
+		# A number arrives from JSON as a float, and 5 was quoted back as 5.0.
+		var given: String = str(index) if index >= 0 else str(which)
+		var among: String = (
+			'the only match on screen%s saying "%s" is index 0' % [under, wanted]
+			if targets.size() == 1
+			else (
+				'the %d matches on screen%s saying "%s" are 0 to %d'
+				% [targets.size(), under, wanted, targets.size() - 1]
+			)
+		)
 		return {
 			"type": "error",
-			"message":
-			(
-				'index %s is not one of the %d control%s on screen%s saying "%s": %s'
-				% [str(which), targets.size(), plural, under, wanted, _candidates(targets, lines)]
-			)
+			"message": "index %s picks nothing: %s: %s" % [given, among, _candidates(targets, lines)]
 		}
 	# A match saying the words as part of more, while another control says exactly them, is a stand-in
 	# for that one, not the control meant: a tab reading "Out" sat in a collapsed drawer and a dispatch

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

@@ -477,5 +477,7 @@ func _element(item: Variant, builtin: int, declared: String, script: Script, res
 		var wanted: String = type_string(builtin)
 		if builtin == TYPE_OBJECT:
 			wanted = declared if script == null else script_named(script)
-		return {"message": "is %s, which cannot become %s" % [JSON.stringify(serialize(item)), wanted]}
+		return {
+			"message": "is %s, which cannot become %s" % [JSON.stringify(serialize(item), "", false), wanted]
+		}
 	return {"value": fitted_item}

package/build/godot/addons/gdharness_runtime/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/operations/animation_reads.gd

@@ -5,6 +5,7 @@ extends RefCounted
 ## stores, which runs no script of the scene's, so a read answers the same either way.
 
 const FileReads = preload("file_reads.gd")
+const Read = preload("reading.gd")
 const Serialisation = preload("serialisation.gd")
 
 const LOOP_MODE_NAMES: Dictionary[int, String] = {
@@ -60,7 +61,15 @@ static func _bare(scene_path: String, node_path: String, kind: String) -> Array:
 		return [null, read]
 	var type: String = str(read.get("type", ""))
 	if not ClassDB.class_exists(type) or not ClassDB.is_parent_class(type, kind):
-		return [null, {"ok": false, "error": "%s not found at: %s" % [kind, node_path]}]
+		var said: String = "%s not found at: %s" % [kind, node_path]
+		if read.is_empty():
+			var hinted: String = said
+			if FileReads.scene_node(scene_path, node_path.get_slice("/", 0)).is_empty():
+				hinted = Read.from_the_root(
+					said, node_path, str(FileReads.scene_node(scene_path, ".").get("name", ""))
+				)
+			said = hinted if hinted != said else FileReads.missing_from(said, scene_path, node_path)
+		return [null, {"ok": false, "error": said}]
 	var bare: Node = ClassDB.instantiate(type)
 	bare.name = str(read["name"])
 	var given: Dictionary = read["properties"]
@@ -164,7 +173,10 @@ static func state_machine(tree: AnimationTree, state_machine_path: String) -> An
 ## the path that failed, and what is there instead.
 static func no_machine(tree: AnimationTree, state_machine_path: String) -> String:
 	if tree == null or tree.tree_root == null:
-		return "The AnimationTree has no tree_root."
+		return (
+			"The AnimationTree has no tree_root. Make one with resource_edit create of an "
+			+ "AnimationNodeStateMachine, then give its res:// path to tree_root with scene_node set."
+		)
 	var current: AnimationNodeStateMachine = tree.tree_root as AnimationNodeStateMachine
 	if current == null:
 		return (

package/build/godot/operations/editor_tools.gd

@@ -7,8 +7,10 @@ extends RefCounted
 ## made here passes the same checks and answers in the same shape. What the engine does that an
 ## editor does not, running every script, is put back in scene_file.gd and headless_check.gd.
 
+const AnimationTools = preload("../addons/gdharness_editor/tools/animation_tools.gd")
 const ResourceTools = preload("../addons/gdharness_editor/tools/resource_tools.gd")
 const SceneTools = preload("../addons/gdharness_editor/tools/scene_tools.gd")
+const SceneFile = preload("../addons/gdharness_editor/scene_file.gd")
 
 const SCENE_COMMANDS: Array[String] = [
 	"create_scene",
@@ -32,6 +34,12 @@ const RESOURCE_COMMANDS: Array[String] = [
 	"set_theme_color",
 	"set_theme_font_size",
 ]
+const ANIMATION_COMMANDS: Array[String] = [
+	"create_animation",
+	"add_animation_track",
+	"add_animation_state",
+	"connect_animation_states",
+]
 
 
 ## Runs the tool [code]command[/code] names with [code]arguments[/code], answering what it answers.
@@ -46,12 +54,31 @@ static func run(params: Dictionary) -> Dictionary:
 		tools = SceneTools.new()
 	elif command in RESOURCE_COMMANDS:
 		tools = ResourceTools.new()
+	elif command in ANIMATION_COMMANDS:
+		tools = AnimationTools.new()
 	else:
 		return {"ok": false, "error": "No editor tool runs headless as " + command}
 	var answer: Variant = tools.call(command, arguments)
 	tools.free()
 	if answer is Dictionary:
-		return answer
+		var answered: Dictionary = answer
+		if not SceneFile.by_path.is_empty():
+			answered["namedByPath"] = (
+				(
+					"%s %s named by path rather than by uid. A uid in a file's own header is resolved "
+					+ "through the project's uid cache, which holds none for %s yet, as with a file "
+					+ "made since the project was last scanned, and a uid it does not hold would warn "
+					+ "on every load. project_import refresh_uids scans the project, and writes after "
+					+ "it name %s by uid."
+				)
+				% [
+					", ".join(SceneFile.by_path),
+					"is" if SceneFile.by_path.size() == 1 else "are",
+					"it" if SceneFile.by_path.size() == 1 else "them",
+					"it" if SceneFile.by_path.size() == 1 else "them",
+				]
+			)
+		return answered
 	return {
 		"ok": false, "error": "%s answered %s rather than an object." % [command, type_string(typeof(answer))]
 	}