gdharness 1.3.8 → 1.3.10

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 GdhFileReads = preload("file_reads.gd")
+const GdhRead = preload("reading.gd")
 const GdhSerialisation = preload("serialisation.gd")
 
 const LOOP_MODE_NAMES: Dictionary[int, String] = {
@@ -28,6 +29,11 @@ const SWITCH_MODE_NAMES: Dictionary[int, String] = {
 	AnimationNodeStateMachineTransition.SWITCH_MODE_SYNC: "sync",
 	AnimationNodeStateMachineTransition.SWITCH_MODE_AT_END: "at_end",
 }
+const ADVANCE_MODE_NAMES: Dictionary[int, String] = {
+	AnimationNodeStateMachineTransition.ADVANCE_MODE_DISABLED: "disabled",
+	AnimationNodeStateMachineTransition.ADVANCE_MODE_ENABLED: "enabled",
+	AnimationNodeStateMachineTransition.ADVANCE_MODE_AUTO: "auto",
+}
 
 
 ## [method animations] of the AnimationPlayer at [param player_path] in the file [param scene_path].
@@ -47,8 +53,21 @@ static func scene_states(scene_path: String, tree_path: String, state_machine_pa
 	if made[0] == null:
 		return made[1]
 	var tree: AnimationTree = made[0]
-	var answer: Dictionary = states(tree, state_machine_path)
+	# The player the tree plays from, read from the file the same way, since a bare tree has no
+	# siblings to find it among.
+	# A path above the root names no node the file has, and finds none, as the editor finds none.
+	var player: AnimationPlayer = null
+	var player_path: String = ""
+	if not str(tree.anim_player).is_empty():
+		player_path = (tree_path + "/" + str(tree.anim_player)).simplify_path()
+		if player_path.is_empty():
+			player_path = "."
+		var found: Array = _bare(scene_path, player_path, "AnimationPlayer")
+		player = found[0]
+	var answer: Dictionary = states(tree, state_machine_path, player, player_path)
 	tree.free()
+	if player != null:
+		player.free()
 	return answer
 
 
@@ -200,8 +219,28 @@ static func no_machine(tree: AnimationTree, state_machine_path: String) -> Strin
 	return "No state machine at " + state_machine_path
 
 
+## Why a state playing [param animation_name] from [param player], at [param player_path] from the
+## scene root as playerNodePath takes it, plays nothing yet. anim_player is relative to the tree
+## ("../Anim"), which no argument takes.
+static func missing_animation(player: AnimationPlayer, player_path: String, 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."
+		% [player_path, 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)]
+	)
+
+
 ## The states and transitions of the state machine at [param state_machine_path] in [param tree].
-static func states(tree: AnimationTree, state_machine_path: String) -> Dictionary:
+## A state playing an animation says whether [param player], at [param player_path], has it, as
+## add_state answers: a state naming one it lacks plays nothing, and says so only in a log.
+static func states(
+	tree: AnimationTree, state_machine_path: String, player: AnimationPlayer, player_path: String
+) -> Dictionary:
 	var sm: AnimationNodeStateMachine = state_machine(tree, state_machine_path)
 	if sm == null:
 		return {"ok": false, "error": no_machine(tree, state_machine_path)}
@@ -212,6 +251,10 @@ static func states(tree: AnimationTree, state_machine_path: String) -> Dictionar
 		if node is AnimationNodeAnimation:
 			var plays: AnimationNodeAnimation = node
 			entry["animationName"] = str(plays.animation)
+			var found: bool = player != null and player.has_animation(plays.animation)
+			entry["animationFound"] = found
+			if player != null and not found:
+				entry["animationMissing"] = missing_animation(player, player_path, str(plays.animation))
 		listed.append(entry)
 	var transitions: Array[Dictionary] = []
 	for index: int in sm.get_transition_count():
@@ -220,8 +263,76 @@ static func states(tree: AnimationTree, state_machine_path: String) -> Dictionar
 			"from": str(sm.get_transition_from(index)),
 			"to": str(sm.get_transition_to(index)),
 			"transitionType": SWITCH_MODE_NAMES.get(transition.switch_mode, str(transition.switch_mode)),
+			"advanceMode": ADVANCE_MODE_NAMES.get(transition.advance_mode, str(transition.advance_mode)),
 		}
-		if not str(transition.advance_condition).is_empty():
-			shaped["advanceCondition"] = str(transition.advance_condition)
+		var condition: String = str(transition.advance_condition)
+		if not condition.is_empty():
+			shaped["advanceCondition"] = condition
+		# A condition is checked only on an auto transition, and the default is enabled: a machine
+		# with its conditions set true stayed where it was, and nothing said why.
+		if not condition.is_empty() and transition.advance_mode != transition.ADVANCE_MODE_AUTO:
+			shaped["conditionNote"] = (
+				(
+					"advanceMode is %s, so %s never advances it: the engine checks a condition only on an"
+					+ " auto transition%s. disconnect_states and connect_states again with the condition"
+					+ " write it as auto"
+				)
+				% [
+					shaped["advanceMode"],
+					condition,
+					(
+						", and travel() still takes this one"
+						if transition.advance_mode == transition.ADVANCE_MODE_ENABLED
+						else ""
+					)
+				]
+			)
 		transitions.append(shaped)
 	return {"ok": true, "states": listed, "transitions": transitions}
+
+
+## The states of the AnimationTrees under [param root] that play [param animation_name] from
+## [param player], as [[node, {animTreePath, state}]], a state named by the path of the nodes leading
+## to it.
+static func states_playing(root: Node, player: AnimationPlayer, animation_name: String) -> Array:
+	var found: Array = []
+	var trees: Array[Node] = root.find_children("*", "AnimationTree", true, false)
+	if root is AnimationTree:
+		trees.append(root)
+	for node: Node in trees:
+		var tree: AnimationTree = node
+		if tree.tree_root == null or tree.get_node_or_null(tree.anim_player) != player:
+			continue
+		var tree_path: String = str(root.get_path_to(tree))
+		_collect_playing(tree.tree_root, "", tree_path, animation_name, found)
+	return found
+
+
+static func _collect_playing(
+	node: AnimationNode, at: String, tree_path: String, animation_name: String, found: Array
+) -> void:
+	if node is AnimationNodeAnimation:
+		var plays: AnimationNodeAnimation = node
+		if plays.animation == StringName(animation_name):
+			found.append([plays, {"animTreePath": tree_path, "state": "." if at.is_empty() else at}])
+		return
+	var children: Dictionary = {}
+	if node is AnimationNodeStateMachine:
+		var machine: AnimationNodeStateMachine = node
+		for state: StringName in machine.get_node_list():
+			children[str(state)] = machine.get_node(state)
+	elif node is AnimationNodeBlendTree:
+		var blend: AnimationNodeBlendTree = node
+		for input: StringName in blend.get_node_list():
+			children[str(input)] = blend.get_node(input)
+	elif node is AnimationNodeBlendSpace1D:
+		var line: AnimationNodeBlendSpace1D = node
+		for point: int in line.get_blend_point_count():
+			children[str(point)] = line.get_blend_point_node(point)
+	elif node is AnimationNodeBlendSpace2D:
+		var plane: AnimationNodeBlendSpace2D = node
+		for point: int in plane.get_blend_point_count():
+			children[str(point)] = plane.get_blend_point_node(point)
+	for step: String in children:
+		var child: AnimationNode = children[step]
+		_collect_playing(child, step if at.is_empty() else at + "/" + step, tree_path, animation_name, found)

package/build/godot/operations/audio_buses.gd

@@ -19,7 +19,7 @@ func create_audio_bus(params: Dictionary) -> Dictionary:
 		return _log.failure("bus_name is required")
 	var parent_idx: int = GdhRead.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))
+		return _log.failure(_no_index(parent_idx))
 	# 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:
@@ -50,10 +50,7 @@ func remove_audio_bus(params: Dictionary) -> Dictionary:
 		return _log.failure("bus_name is required")
 	var index: int = AudioServer.get_bus_index(bus_name)
 	if index == -1:
-		var names: Array[String] = []
-		for i: int in range(AudioServer.bus_count):
-			names.append(AudioServer.get_bus_name(i))
-		return _log.failure("No bus named %s. The buses are %s." % [bus_name, ", ".join(names)])
+		return _log.failure("No bus named %s. The buses are %s." % [bus_name, ", ".join(_names())])
 	if index == 0:
 		return _log.failure("%s is the bus every other ends in, so it cannot be removed." % bus_name)
 
@@ -105,7 +102,7 @@ func set_audio_bus_effect(params: Dictionary) -> Dictionary:
 	var effect_type: String = str(params.get("effect_type", ""))
 	var enabled: bool = GdhRead.as_bool(params.get("enabled", true), true)
 	if bus_idx < 0 or bus_idx >= AudioServer.bus_count:
-		return _log.failure("No bus at index " + str(bus_idx))
+		return _log.failure(_no_index(bus_idx))
 
 	var effect: AudioEffect = _effect_named(effect_type)
 	if effect == null:
@@ -153,7 +150,7 @@ func set_audio_bus_volume(params: Dictionary) -> Dictionary:
 	var bus_idx: int = GdhRead.as_int(params.get("bus_index", 0))
 	var volume_db: float = GdhRead.as_float(params.get("volume_db", 0.0))
 	if bus_idx < 0 or bus_idx >= AudioServer.bus_count:
-		return _log.failure("No bus at index " + str(bus_idx))
+		return _log.failure(_no_index(bus_idx))
 
 	AudioServer.set_bus_volume_db(bus_idx, volume_db)
 
@@ -163,6 +160,95 @@ func set_audio_bus_volume(params: Dictionary) -> Dictionary:
 	return {"bus": _bus(bus_idx), "layout": layout}
 
 
+## Renames a bus, and every send to it with it: the engine renames the one bus and leaves a bus that
+## sent to it sending to a name nothing has, which it reads as Master. The scenes naming it are the
+## server's to rewrite, since they are files rather than anything this process holds.
+func rename_audio_bus(params: Dictionary) -> Dictionary:
+	var bus_name: String = str(params.get("bus_name", ""))
+	var new_name: String = str(params.get("new_bus_name", ""))
+	if bus_name.is_empty() or new_name.is_empty():
+		return _log.failure("bus_name and new_bus_name are required")
+	var index: int = AudioServer.get_bus_index(bus_name)
+	if index == -1:
+		return _log.failure("No bus named %s. The buses are %s." % [bus_name, ", ".join(_names())])
+	if index == 0:
+		return _log.failure(
+			"%s is the bus every other ends in, which the editor keeps under its name." % bus_name
+		)
+	var existing: int = AudioServer.get_bus_index(new_name)
+	if existing != -1:
+		return _log.failure("A bus named " + new_name + " already exists, at index " + str(existing))
+	AudioServer.set_bus_name(index, new_name)
+	var resent: Array[String] = []
+	for i: int in range(AudioServer.bus_count):
+		if AudioServer.get_bus_send(i) == bus_name:
+			AudioServer.set_bus_send(i, new_name)
+			resent.append(AudioServer.get_bus_name(i))
+
+	var layout: String = _save_layout()
+	if layout.is_empty():
+		return {}
+	var answer: Dictionary = {
+		"renamed": {"from": bus_name, "to": new_name}, "bus": _bus(index), "layout": layout
+	}
+	if not resent.is_empty():
+		answer["resent"] = resent
+	return answer
+
+
+## Points a bus's send at another bus. Only one before it: the editor offers no other, and the
+## engine takes any name, a later bus, the bus itself or one that does not exist, without a word.
+func set_audio_bus_send(params: Dictionary) -> Dictionary:
+	var bus_idx: int = GdhRead.as_int(params.get("bus_index", 0))
+	var send: String = str(params.get("send_to", ""))
+	if bus_idx < 0 or bus_idx >= AudioServer.bus_count:
+		return _log.failure(_no_index(bus_idx))
+	var bus_name: String = AudioServer.get_bus_name(bus_idx)
+	if bus_idx == 0:
+		return _log.failure("%s sends nowhere: it is the bus every other ends in." % bus_name)
+	var target: int = AudioServer.get_bus_index(send)
+	if target == -1:
+		return _log.failure("No bus named %s. The buses are %s." % [send, ", ".join(_names())])
+	if target == bus_idx:
+		return _log.failure(
+			"%s cannot send to itself; it can send to %s." % [bus_name, ", ".join(_names().slice(0, bus_idx))]
+		)
+	if target > bus_idx:
+		return (
+			_log
+			. failure(
+				(
+					(
+						"%s is bus %d and %s is bus %d: a bus sends only to one before it, which keeps sound from "
+						+ "going round in a loop, so %s can send to %s."
+					)
+					% [bus_name, bus_idx, send, target, bus_name, ", ".join(_names().slice(0, bus_idx))]
+				)
+			)
+		)
+	AudioServer.set_bus_send(bus_idx, send)
+
+	var layout: String = _save_layout()
+	if layout.is_empty():
+		return {}
+	return {"bus": _bus(bus_idx), "layout": layout}
+
+
+func _names() -> Array[String]:
+	var names: Array[String] = []
+	for i: int in range(AudioServer.bus_count):
+		names.append(AudioServer.get_bus_name(i))
+	return names
+
+
+## The refusal for a bus index nothing is at, with each bus at its index, so the caller has one.
+func _no_index(index: int) -> String:
+	var held: PackedStringArray = []
+	for i: int in range(AudioServer.bus_count):
+		var _added: bool = held.append("%d %s" % [i, AudioServer.get_bus_name(i)])
+	return "No bus at index %d; the buses are %s." % [index, ", ".join(held)]
+
+
 func _bus(index: int) -> Dictionary:
 	var effects: Array[Dictionary] = []
 	for e: int in range(AudioServer.get_bus_effect_count(index)):

package/build/godot/operations/classdb_queries.gd

@@ -93,6 +93,19 @@ func query_classes(params: Dictionary) -> Dictionary:
 
 		filtered_classes.append(class_name_str)
 
+	var declared: Dictionary = _declared_classes(params)
+	var own: Array[Dictionary] = []
+	for name: String in _sorted_names(declared):
+		if instantiable_only and not _instantiable(name, declared):
+			continue
+		if not filter.is_empty() and not name.to_lower().contains(filter.to_lower()):
+			continue
+		if not bases.is_empty():
+			var engine_base: String = _engine_base_of(name, declared)
+			if engine_base.is_empty() or not _under_any(engine_base, bases):
+				continue
+		own.append(_project_entry(name, declared))
+
 	_log.info(
 		"Found " + str(filtered_classes.size()) + " classes (out of " + str(all_classes.size()) + " total)"
 	)
@@ -103,7 +116,8 @@ func query_classes(params: Dictionary) -> Dictionary:
 		"filter": filter,
 		"category": category,
 		"instantiable_only": instantiable_only,
-		"classes": filtered_classes
+		"classes": filtered_classes,
+		"project_classes": own,
 	}
 
 
@@ -194,6 +208,8 @@ static func _names(members: Array[Dictionary]) -> Array[String]:
 	return names
 
 
+## What the project's scripts declare on disk, class to its path, what it extends and whether it is
+## abstract, as the server read them.
 static func _declared_classes(params: Dictionary) -> Dictionary:
 	var given: Variant = params.get("project_classes", {})
 	if given is Dictionary:
@@ -202,12 +218,75 @@ static func _declared_classes(params: Dictionary) -> Dictionary:
 	return {}
 
 
+static func _entry_of(name: String, declared: Dictionary) -> Dictionary:
+	var entry: Variant = declared.get(name, {})
+	if entry is Dictionary:
+		var fields: Dictionary = entry
+		return fields
+	return {}
+
+
+static func _sorted_names(declared: Dictionary) -> Array[String]:
+	var names: Array[String] = []
+	for name: Variant in declared.keys():
+		names.append(str(name))
+	names.sort()
+	return names
+
+
+## [param name]'s ancestors, nearest first: the project classes it extends, then the engine's. A
+## base that is neither ends the line, as it is written.
+static func _ancestors_of(name: String, declared: Dictionary) -> Array[String]:
+	var ancestors: Array[String] = []
+	var current: String = name
+	while declared.has(current):
+		var base: String = str(_entry_of(current, declared).get("extends", ""))
+		if base.is_empty() or base == name or ancestors.has(base):
+			return ancestors
+		ancestors.append(base)
+		current = base
+	while ClassDB.class_exists(current):
+		var parent: String = ClassDB.get_parent_class(current)
+		if parent.is_empty():
+			break
+		ancestors.append(parent)
+		current = parent
+	return ancestors
+
+
+## The engine class [param name] is built on, or empty when its line reaches none.
+static func _engine_base_of(name: String, declared: Dictionary) -> String:
+	if not declared.has(name):
+		return name if ClassDB.class_exists(name) else ""
+	for each: String in _ancestors_of(name, declared):
+		if ClassDB.class_exists(each):
+			return each
+	return ""
+
+
+static func _instantiable(name: String, declared: Dictionary) -> bool:
+	if GdhRead.as_bool(_entry_of(name, declared).get("abstract", false)):
+		return false
+	var engine_base: String = _engine_base_of(name, declared)
+	return not engine_base.is_empty() and ClassDB.can_instantiate(engine_base)
+
+
+static func _project_entry(name: String, declared: Dictionary) -> Dictionary:
+	var entry: Dictionary = _entry_of(name, declared)
+	return {
+		"name": name,
+		"path": str(entry.get("path", "")),
+		"extends": str(entry.get("extends", "")),
+		"abstract": GdhRead.as_bool(entry.get("abstract", false)),
+	}
+
+
 ## Why [param wanted] has no answer here. A class_name a project script declares is not in ClassDB,
 ## and "Class not found" for one read as though the project had no such class. [param declared] is
 ## what the project's scripts declare on disk, class to path, rather than the engine's list, which is
 ## the class cache: that lags the scripts, and a class written a moment ago was refused as declared
 ## nowhere.
-func _not_found(wanted: String, declared: Dictionary) -> Dictionary:
+func _not_found(wanted: String, declared: Dictionary, answers_own: bool = false) -> Dictionary:
 	if declared.has(wanted):
 		return _log.failure(
 			(
@@ -216,7 +295,7 @@ func _not_found(wanted: String, declared: Dictionary) -> Dictionary:
 					+ "the engine's ClassDB only. script_info structure on that script, with "
 					+ "includeInherited, answers what it declares and what it inherits."
 				)
-				% [wanted, str(declared[wanted])]
+				% [wanted, str(_entry_of(wanted, declared).get("path", ""))]
 			)
 		)
 	# The usual miss is a spelling, one letter off a class the engine has or one the project declares.
@@ -245,13 +324,18 @@ func _not_found(wanted: String, declared: Dictionary) -> Dictionary:
 	)
 	if not own.is_empty():
 		offered += (
-			" The nearest %s a project script declares %s %s, which script_info structure reads."
+			" The nearest %s a project script declares %s %s%s."
 			% [
 				"class" if own.size() == 1 else "classes",
 				"is" if own.size() == 1 else "are",
 				", ".join(own),
+				"" if answers_own else ", which script_info structure reads",
 			]
 		)
+	if answers_own:
+		return _log.failure(
+			"Class not found: %s.%s Neither the engine nor a project script declares it." % [wanted, offered]
+		)
 	return _log.failure(
 		(
 			(
@@ -340,8 +424,34 @@ func inspect_inheritance(params: Dictionary) -> Dictionary:
 
 	_log.info("Inspecting inheritance for: " + class_name_str)
 
-	if not ClassDB.class_exists(class_name_str):
-		return _not_found(class_name_str, _declared_classes(params))
+	var declared: Dictionary = _declared_classes(params)
+	var own_class: bool = declared.has(class_name_str)
+	if not own_class and not ClassDB.class_exists(class_name_str):
+		return _not_found(class_name_str, declared, true)
+
+	# A class a project script declares can stand only under another or under an engine class, so
+	# both answers carry the project's own beneath the class asked about.
+	var project_children: Array[Dictionary] = []
+	var project_descendants: Array[Dictionary] = []
+	for name: String in _sorted_names(declared):
+		var line: Array[String] = _ancestors_of(name, declared)
+		if name == class_name_str or not line.has(class_name_str):
+			continue
+		project_descendants.append(_project_entry(name, declared))
+		if line[0] == class_name_str:
+			project_children.append(_project_entry(name, declared))
+	if own_class:
+		var own_line: Array[String] = _ancestors_of(class_name_str, declared)
+		return {
+			"class_name": class_name_str,
+			"declared_in": str(_entry_of(class_name_str, declared).get("path", "")),
+			"parent_class": "" if own_line.is_empty() else own_line[0],
+			"ancestors": own_line,
+			"abstract": GdhRead.as_bool(_entry_of(class_name_str, declared).get("abstract", false)),
+			"can_instantiate": _instantiable(class_name_str, declared),
+			"project_children": project_children,
+			"project_descendants": project_descendants,
+		}
 
 	var ancestors: Array[String] = []
 	var current: String = class_name_str
@@ -386,7 +496,9 @@ func inspect_inheritance(params: Dictionary) -> Dictionary:
 		"direct_children": direct_children,
 		"all_descendants_count": all_descendants.size(),
 		"all_descendants": all_descendants,
-		"can_instantiate": ClassDB.can_instantiate(class_name_str)
+		"can_instantiate": ClassDB.can_instantiate(class_name_str),
+		"project_children": project_children,
+		"project_descendants": project_descendants,
 	}