gdharness 1.3.3 → 1.3.4

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

@@ -29,18 +29,6 @@ func set_editor_plugin(plugin: EditorPlugin) -> void:
 # =============================================================================
 # Shared helpers
 # =============================================================================
-func _ensure_res_path(path: String) -> String:
-	if not path.begins_with("res://"):
-		return "res://" + path
-	return path
-
-
-func _find_node(root: Node, path: String) -> Node:
-	if path == "." or path.is_empty():
-		return root
-	return root.get_node_or_null(path)
-
-
 ## [param scene_path] opened for writing, with the node at [param node_path] in it, which must be a
 ## [param kind] the scene owns. Answers [scene, node, refusal]; the refusal is {} when both were
 ## found.
@@ -49,7 +37,7 @@ func _open_at(scene_path: String, node_path: String, kind: String) -> Array:
 	var refused: Dictionary = scene.open(scene_path, true)
 	if not refused.is_empty():
 		return [scene, null, refused]
-	var node: Node = _find_node(scene.root, node_path)
+	var node: Node = GdhSceneFile.node_at(scene.root, node_path)
 	if node == null or not node.is_class(kind):
 		return [scene, null, _not_of_kind(scene, node, node_path, kind)]
 	var foreign: String = scene.foreign(node)
@@ -65,7 +53,7 @@ func _read_at(scene_path: String, node_path: String, kind: String) -> Array:
 	var refused: Dictionary = scene.open(scene_path, false)
 	if not refused.is_empty():
 		return [scene, null, refused]
-	var node: Node = _find_node(scene.root, node_path)
+	var node: Node = GdhSceneFile.node_at(scene.root, node_path)
 	if node == null or not node.is_class(kind):
 		return [scene, null, _not_of_kind(scene, node, node_path, kind)]
 	return [scene, node, {}]
@@ -233,7 +221,7 @@ func _animated(player: AnimationPlayer, track_path: String) -> Node:
 ## The animations of an AnimationPlayer, or one of them whole. A track comes back in the shape
 ## add_track takes, so one read here can be written to another animation as it stands.
 func read_animations(args: Dictionary) -> Dictionary:
-	var scene_path: String = _ensure_res_path(str(args.get("scenePath", "")))
+	var scene_path: String = GdhSceneFile.res_path("", str(args.get("scenePath", "")))
 	var player_node_path: String = str(args.get("playerNodePath", "."))
 	var animation_name: String = str(args.get("animationName", ""))
 	if scene_path.strip_edges() == "res://":
@@ -258,7 +246,7 @@ func _read_in(scene: GdhSceneFile, answer: Dictionary) -> Dictionary:
 
 ## The states and transitions of a state machine in an AnimationTree.
 func read_animation_states(args: Dictionary) -> Dictionary:
-	var scene_path: String = _ensure_res_path(str(args.get("scenePath", "")))
+	var scene_path: String = GdhSceneFile.res_path("", str(args.get("scenePath", "")))
 	var anim_tree_path: String = str(args.get("animTreePath", ""))
 	var state_machine_path: String = str(args.get("stateMachinePath", ""))
 	if scene_path.strip_edges() == "res://":
@@ -278,7 +266,7 @@ func read_animation_states(args: Dictionary) -> Dictionary:
 # create_animation
 # =============================================================================
 func create_animation(args: Dictionary) -> Dictionary:
-	var scene_path: String = _ensure_res_path(str(args.get("scenePath", "")))
+	var scene_path: String = GdhSceneFile.res_path("", str(args.get("scenePath", "")))
 	var player_node_path: String = str(args.get("playerNodePath", "."))
 	var animation_name: String = str(args.get("animationName", ""))
 	var loop_mode_name: String = str(args.get("loopMode", "none"))
@@ -335,7 +323,7 @@ func create_animation(args: Dictionary) -> Dictionary:
 # add_animation_track
 # =============================================================================
 func add_animation_track(args: Dictionary) -> Dictionary:
-	var scene_path: String = _ensure_res_path(str(args.get("scenePath", "")))
+	var scene_path: String = GdhSceneFile.res_path("", str(args.get("scenePath", "")))
 	var player_node_path: String = str(args.get("playerNodePath", "."))
 	var animation_name: String = str(args.get("animationName", ""))
 	var given_track: Variant = args.get("track", {})
@@ -553,7 +541,7 @@ func _key_values(target: Node, prop_name: String, keyframes: Array) -> Array:
 	var base: String = prop_name.get_slice(":", 0)
 	var declared: Dictionary = _properties.declaration(target, base)
 	if declared.is_empty():
-		return [false, "%s has no property %s" % [target.get_class(), base]]
+		return [false, GdhPropertyValues.no_property(target, base)]
 	var values: Array = []
 	for index: int in keyframes.size():
 		var keyframe: Dictionary = keyframes[index]
@@ -612,7 +600,7 @@ func _animation_at(scene_path: String, player_node_path: String, animation_name:
 ## Changes the length, loop mode or step of an animation, naming any key a shorter length leaves
 ## past the end.
 func set_animation(args: Dictionary) -> Dictionary:
-	var scene_path: String = _ensure_res_path(str(args.get("scenePath", "")))
+	var scene_path: String = GdhSceneFile.res_path("", str(args.get("scenePath", "")))
 	var player_node_path: String = str(args.get("playerNodePath", "."))
 	var animation_name: String = str(args.get("animationName", ""))
 	var loop_mode_name: String = str(args.get("loopMode", ""))
@@ -673,7 +661,7 @@ func set_animation(args: Dictionary) -> Dictionary:
 ## the scene's trees that plays it, since a state naming an animation the player lacks plays nothing
 ## and says so only in the editor's log.
 func rename_animation(args: Dictionary) -> Dictionary:
-	var scene_path: String = _ensure_res_path(str(args.get("scenePath", "")))
+	var scene_path: String = GdhSceneFile.res_path("", str(args.get("scenePath", "")))
 	var player_node_path: String = str(args.get("playerNodePath", "."))
 	var animation_name: String = str(args.get("animationName", ""))
 	var new_name: String = str(args.get("newName", "")).strip_edges()
@@ -752,7 +740,7 @@ func rename_animation(args: Dictionary) -> Dictionary:
 ## Removes an animation, clearing the player's autoplay when it named it and naming the states of
 ## the scene's trees left playing nothing.
 func remove_animation(args: Dictionary) -> Dictionary:
-	var scene_path: String = _ensure_res_path(str(args.get("scenePath", "")))
+	var scene_path: String = GdhSceneFile.res_path("", str(args.get("scenePath", "")))
 	var player_node_path: String = str(args.get("playerNodePath", "."))
 	var animation_name: String = str(args.get("animationName", ""))
 	if scene_path.strip_edges() == "res://":
@@ -844,7 +832,7 @@ static func _collect_playing(
 # add_animation_state
 # =============================================================================
 func add_animation_state(args: Dictionary) -> Dictionary:
-	var scene_path: String = _ensure_res_path(str(args.get("scenePath", "")))
+	var scene_path: String = GdhSceneFile.res_path("", str(args.get("scenePath", "")))
 	var anim_tree_path: String = str(args.get("animTreePath", ""))
 	var state_name: String = str(args.get("stateName", ""))
 	var animation_name: String = str(args.get("animationName", ""))
@@ -872,15 +860,7 @@ func add_animation_state(args: Dictionary) -> Dictionary:
 	if sm.has_node(StringName(state_name)):
 		return scene.refuse("The state machine already has a state named %s." % state_name)
 	var player: AnimationPlayer = anim_tree.get_node_or_null(anim_tree.anim_player) as AnimationPlayer
-	if player != null and not player.has_animation(StringName(animation_name)):
-		# By its path from the scene root, as playerNodePath takes it; anim_player is relative to the
-		# tree ("../Anim"), which no argument takes.
-		return scene.refuse(
-			(
-				"The AnimationPlayer at %s has no animation %s for the state to play."
-				% [str(scene.root.get_path_to(player)), animation_name]
-			)
-		)
+	var found: bool = player != null and player.has_animation(StringName(animation_name))
 
 	var anim_node: AnimationNodeAnimation = AnimationNodeAnimation.new()
 	anim_node.animation = StringName(animation_name)
@@ -900,19 +880,42 @@ func add_animation_state(args: Dictionary) -> Dictionary:
 		"ok": true,
 		"stateName": state_name,
 		"animationName": animation_name,
-		# False when the tree has no player to look the animation up in.
-		"animationFound": player != null,
+		# False when the tree has no player to look the animation up in, or its player has none of
+		# that name.
+		"animationFound": found,
 		"position": GdhSerialisation.new().serialize_value(position),
 	}
+	# Written all the same, as the editor writes one: a state machine is often laid out before its
+	# animations are made, and refusing it stopped a tree being built in that order.
+	if player != null and not found:
+		answer["animationMissing"] = _missing_animation(scene, player, animation_name)
 	var files: Dictionary = machine[1]
 	return _finish(scene, Callable(), files, answer)
 
 
+## Why the state playing [param animation_name] plays nothing yet. The player is named by its path
+## from the scene root, as playerNodePath takes it; anim_player is relative to the tree ("../Anim"),
+## which no argument takes.
+static func _missing_animation(
+	scene: GdhSceneFile, player: AnimationPlayer, animation_name: String
+) -> String:
+	var said: String = (
+		"The AnimationPlayer at %s has no animation %s yet, so the state plays nothing until it has one."
+		% [str(scene.root.get_path_to(player)), animation_name]
+	)
+	var close: PackedStringArray = GdhRead.nearest(animation_name, player.get_animation_list())
+	if close.is_empty():
+		return said
+	return (
+		said + " The nearest %s %s." % ["it has is" if close.size() == 1 else "it has are", ", ".join(close)]
+	)
+
+
 # =============================================================================
 # connect_animation_states
 # =============================================================================
 func connect_animation_states(args: Dictionary) -> Dictionary:
-	var scene_path: String = _ensure_res_path(str(args.get("scenePath", "")))
+	var scene_path: String = GdhSceneFile.res_path("", str(args.get("scenePath", "")))
 	var anim_tree_path: String = str(args.get("animTreePath", ""))
 	var from_state: String = str(args.get("fromState", ""))
 	var to_state: String = str(args.get("toState", ""))

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

@@ -7,6 +7,7 @@ const GdhFileReads = preload("../file_reads.gd")
 const GdhHeadlessCheck = preload("../headless_check.gd")
 const GdhPropertyValues = preload("../property_values.gd")
 const GdhRead = preload("../reading.gd")
+const GdhSame = preload("../same_values.gd")
 const GdhSceneFile = preload("../scene_file.gd")
 
 # The minimal shader of a type: its declaration and the one function the engine calls for it.
@@ -136,7 +137,7 @@ func _save_checked(resource: Resource, path: String, names: Array, previous: Var
 		for key: Variant in names:
 			var property: String = str(key)
 			var read: Variant = _properties.read_at(loaded, property)
-			if not GdhPropertyValues.same(read, _properties.read_at(resource, property)):
+			if not GdhSame.same(read, _properties.read_at(resource, property)):
 				lost = (
 					(
 						"%s.%s would load from the file as %s: it is not a property the file keeps, so "
@@ -182,7 +183,7 @@ func _unkept_headless(resource: Resource, path: String, names: Array, previous:
 		var property: String = str(key)
 		asked[property] = true
 		asked[property.get_slice(":", 0)] = true
-		reached.merge(GdhHeadlessCheck.reached(resource, property))
+		GdhHeadlessCheck.spare(reached, GdhHeadlessCheck.reached(resource, property))
 	return GdhHeadlessCheck.settle_saved(
 		path,
 		before,

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

@@ -0,0 +1,91 @@
+@tool
+extends RefCounted
+
+## The groups a node of a scene is in. A scene's own file puts a node in a group and can take it
+## out of one it put it in; a group the scene that makes the node puts it in, the one it is
+## instanced from or one this scene inherits, can be changed only there, as the editor's group dock
+## shows it locked.
+
+const GdhSceneFile = preload("../scene_file.gd")
+
+
+## The groups of [param node], sorted, as {groups, groupsHere}: groupsHere, those this scene's file
+## puts it in, is given only where another scene puts it in some of them. Empty for a node in none.
+static func read(scene: GdhSceneFile, node: Node) -> Dictionary:
+	var all: Array = _sorted(node.get_groups())
+	if all.is_empty():
+		return {}
+	var answer: Dictionary = {"groups": all}
+	var here: Array = _sorted(scene.groups_at(scene.path_of(node)))
+	if here.size() != all.size():
+		answer["groupsHere"] = here
+	return answer
+
+
+## The group names under [param key] of [param args], which the server has checked are strings, or
+## none when not given.
+static func asked(args: Dictionary, key: String) -> Array:
+	var given: Variant = args.get(key)
+	return given if given is Array else []
+
+
+## Puts [param node] in each group of [param adding] and takes it out of each of [param removing],
+## or answers why not with nothing changed.
+static func change(scene: GdhSceneFile, node: Node, adding: Array, removing: Array) -> String:
+	for group: Variant in adding + removing:
+		if str(group).strip_edges().is_empty():
+			return (
+				"%s names no group: a group's name has something in it besides spaces."
+				% JSON.stringify(group)
+			)
+	for group: Variant in adding:
+		if removing.has(group):
+			return "%s is in both addGroups and removeGroups." % str(group)
+	var at: String = scene.path_of(node)
+	var here: PackedStringArray = scene.groups_at(at)
+	for group: Variant in removing:
+		var name: String = str(group)
+		if not node.is_in_group(name):
+			var held: Array = _sorted(node.get_groups())
+			return (
+				"%s is in no group %s; %s."
+				% [node.name, name, "it is in " + ", ".join(held) if not held.is_empty() else "it is in none"]
+			)
+		if not here.has(name):
+			var from: String = scene.values_from(node, at)
+			if from.is_empty():
+				return (
+					"%s is in %s, which no scene file puts it in: something puts it there as it is made, such as its script."
+					% [node.name, name]
+				)
+			return (
+				(
+					"%s is in %s because %s puts it there, and no scene using that one can take it out: "
+					+ "remove the group in %s, which takes it out in every scene using that one."
+				)
+				% [node.name, name, from, from]
+			)
+	for group: Variant in adding:
+		node.add_to_group(str(group), true)
+	for group: Variant in removing:
+		node.remove_from_group(str(group))
+	return ""
+
+
+## Why [param saved], the node as the written file loads it, is not in the groups asked, or "".
+static func unkept(saved: Node, adding: Array, removing: Array) -> String:
+	for group: Variant in adding:
+		if not saved.is_in_group(str(group)):
+			return "%s would load in no group %s." % [saved.name, str(group)]
+	for group: Variant in removing:
+		if saved.is_in_group(str(group)):
+			return "%s would still load in the group %s." % [saved.name, str(group)]
+	return ""
+
+
+static func _sorted(groups: Variant) -> Array:
+	var names: Array = []
+	for group: Variant in groups:
+		names.append(str(group))
+	names.sort()
+	return names

package/build/godot/addons/gdharness_editor/tools/scene_groups.gd.uid

@@ -0,0 +1 @@
+uid://76w2hadtl7nab

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

@@ -6,7 +6,7 @@ extends RefCounted
 
 const GdhFileWalk = preload("../file_walk.gd")
 const GdhRead = preload("../reading.gd")
-const GdhPropertyValues = preload("../property_values.gd")
+const GdhSame = preload("../same_values.gd")
 
 
 ## The scene to instance for an add, or null for a node of a class, beside why neither can be made
@@ -85,7 +85,7 @@ static func copied(source: Node, root: Node, copies: Dictionary) -> Node:
 				continue
 			var property: String = str(declared.get("name", ""))
 			var value: Variant = source.get(property)
-			if not GdhPropertyValues.same(copy.get(property), value):
+			if not GdhSame.same(copy.get(property), value):
 				copy.set(property, value)
 		for group: StringName in source.get_groups():
 			if not copy.is_in_group(group):
@@ -171,6 +171,72 @@ static func place(node: Node, asked: Variant) -> void:
 		node.get_parent().move_child(node, GdhRead.as_int(asked))
 
 
+## The properties that hold where [param node] is drawn, which a reparent keeping it in place
+## changes: a Control keeps only its position, as Node.reparent keeps it.
+static func placing(node: Node) -> Array[String]:
+	if node is Node3D:
+		return ["position", "rotation", "scale"]
+	if node is Control:
+		return ["position"]
+	if node is Node2D:
+		return ["position", "rotation", "scale", "skew"]
+	return []
+
+
+## Gives [param node], just moved from under [param was], the transform that keeps it where it was
+## drawn, as the editor's reparent and Node.reparent do. Worked out from the local transforms
+## rather than read off the global ones, which the engine answers only for a node in the tree, and
+## the scene a tool edits is loaded from its file and never is. Nothing changes for a top-level
+## node, or where the old and new parents place their children alike.
+static func keep_in_place(node: Node, was: Node) -> void:
+	if node is Node3D:
+		var spatial: Node3D = node
+		var before: Transform3D = _spatial_space(was)
+		var after: Transform3D = _spatial_space(node.get_parent())
+		if not spatial.top_level and not before.is_equal_approx(after):
+			spatial.transform = after.affine_inverse() * before * spatial.transform
+	elif node is CanvasItem:
+		var drawn: CanvasItem = node
+		var before_2d: Transform2D = _canvas_space(was)
+		var after_2d: Transform2D = _canvas_space(node.get_parent())
+		if drawn.top_level or before_2d.is_equal_approx(after_2d):
+			return
+		var held: Transform2D = after_2d.affine_inverse() * before_2d * drawn.get_transform()
+		if node is Control:
+			var control: Control = node
+			control.position = held.origin
+		else:
+			var flat: Node2D = node
+			flat.transform = held
+
+
+## Where the children of [param parent] are drawn in 3D: the transforms of it and the Node3Ds
+## above it, up to the first that is top-level or whose parent is no Node3D.
+static func _spatial_space(parent: Node) -> Transform3D:
+	var space: Transform3D = Transform3D.IDENTITY
+	var at: Node = parent
+	while at is Node3D:
+		var spatial: Node3D = at
+		space = spatial.transform * space
+		if spatial.top_level:
+			break
+		at = at.get_parent()
+	return space
+
+
+## Where the children of [param parent] are drawn in 2D, as [method _spatial_space] works it out in 3D.
+static func _canvas_space(parent: Node) -> Transform2D:
+	var space: Transform2D = Transform2D.IDENTITY
+	var at: Node = parent
+	while at is CanvasItem:
+		var drawn: CanvasItem = at
+		space = drawn.get_transform() * space
+		if drawn.top_level:
+			break
+		at = at.get_parent()
+	return space
+
+
 ## Why [param instanced] cannot be instanced into [param scene_path], or "" when it can: a scene
 ## inside itself, directly or through the scenes it instances, which Godot's own dialog refuses and
 ## which never finishes loading.