gdharness 1.3.8 → 1.3.10

package/build/godot/addons/gdharness_editor/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/addons/gdharness_editor/declared_values.gd

@@ -6,6 +6,36 @@ extends RefCounted
 
 const GdhRead = preload("reading.gd")
 
+## The section of layer_names in project.godot naming the layers of each layers hint.
+const LAYER_NAMES: Dictionary[int, String] = {
+	PROPERTY_HINT_LAYERS_2D_PHYSICS: "2d_physics",
+	PROPERTY_HINT_LAYERS_2D_RENDER: "2d_render",
+	PROPERTY_HINT_LAYERS_2D_NAVIGATION: "2d_navigation",
+	PROPERTY_HINT_LAYERS_3D_PHYSICS: "3d_physics",
+	PROPERTY_HINT_LAYERS_3D_RENDER: "3d_render",
+	PROPERTY_HINT_LAYERS_3D_NAVIGATION: "3d_navigation",
+	PROPERTY_HINT_LAYERS_AVOIDANCE: "avoidance",
+}
+## How many layers a mask holds, one bit each, whatever the editor names.
+const MASK_LAYERS: int = 32
+
+
+## The layers [param mask] holds under a layers [param hint], each with the name project.godot
+## gives it where it gives one.
+static func layers_in(hint: int, mask: int) -> Array[Dictionary]:
+	var layers: Array[Dictionary] = []
+	for layer: int in range(1, MASK_LAYERS + 1):
+		if mask & (1 << (layer - 1)) == 0:
+			continue
+		var entry: Dictionary = {"layer": layer}
+		var name: String = str(
+			ProjectSettings.get_setting("layer_names/%s/layer_%d" % [LAYER_NAMES[hint], layer], "")
+		)
+		if not name.is_empty():
+			entry["name"] = name
+		layers.append(entry)
+	return layers
+
 
 ## The values an enum hint names, by name, from its hint string: "SWORD:0,SHIELD:1" as a script
 ## declares one, or "Add,Subtract" as an engine property does, each name then taking the number
@@ -127,6 +157,77 @@ static func enum_refusal(
 	return said + ". The nearest %s %s." % ["is" if close.size() == 1 else "are", ", ".join(close)]
 
 
+## Why [param word], given as argument [param index] of [param called] for the enum [param named],
+## names none of its [param choices].
+static func enum_argument_refusal(
+	called: String, index: int, named: String, word: String, choices: Dictionary
+) -> String:
+	var said: String = (
+		"%s takes the enum %s as argument %d, and %s is none of its values: send %s by name or by number"
+		% [called, named, index + 1, word, _listed(choices)]
+	)
+	var close: PackedStringArray = GdhRead.nearest(word, PackedStringArray(choices.keys()))
+	if close.is_empty():
+		return said + "."
+	return said + ". The nearest %s %s." % ["is" if close.size() == 1 else "are", ", ".join(close)]
+
+
+## Why [param value], given as argument [param index] for the enum [param named], is none of its
+## [param choices], or "" when it is one. The engine passes any number on.
+static func outside_enum_argument(index: int, named: String, value: Variant, choices: Dictionary) -> String:
+	if typeof(value) != TYPE_INT or choices.values().has(value):
+		return ""
+	return (
+		"argument %d, %d, is none of the values %s declares: %s."
+		% [index + 1, value, named, _listed(choices)]
+	)
+
+
+## The values of the enum the engine names [param qualified], by name: an engine class's, as
+## Node.ProcessMode, or a script's, as Named.Size for a class_name, res://main.gd.Mood for a script
+## without one, and either followed by inner classes. {} when it names nothing this can read.
+static func enum_declared_as(qualified: String) -> Dictionary:
+	var cut: int = qualified.rfind(".")
+	if cut <= 0:
+		return {}
+	var owner: String = qualified.substr(0, cut)
+	var named: String = qualified.substr(cut + 1)
+	if ClassDB.class_exists(owner):
+		var constants: Dictionary = {}
+		for constant: String in ClassDB.class_get_enum_constants(owner, named):
+			constants[constant] = ClassDB.class_get_integer_constant(owner, constant)
+		return constants
+	var script: Script = _script_named_as(owner)
+	if script == null:
+		return {}
+	var found: Variant = script.get_script_constant_map().get(named)
+	if not found is Dictionary:
+		return {}
+	var values: Dictionary = found
+	return values
+
+
+## The script [param owner] names: a class_name, a res:// path, or an inner class of either after a
+## dot, or null.
+static func _script_named_as(owner: String) -> Script:
+	var by_name: Script = script_class(owner)
+	if by_name != null:
+		return by_name
+	if owner.begins_with("res://") and ResourceLoader.exists(owner):
+		return load(owner) as Script
+	var cut: int = owner.rfind(".")
+	if cut <= 0:
+		return null
+	var outer: Script = _script_named_as(owner.substr(0, cut))
+	if outer == null:
+		return null
+	var inner: Variant = outer.get_script_constant_map().get(owner.substr(cut + 1))
+	if not inner is Script:
+		return null
+	var inner_script: Script = inner
+	return inner_script
+
+
 ## Why [param value], shown as [param shown], lies outside what [param declared] allows, an export
 ## range or an enum's values, or "" when it does not. A range marked or_greater or or_less is open
 ## on that side.
@@ -153,6 +254,19 @@ static func outside(target: Object, declared: Dictionary, value: Variant, shown:
 		if choices.is_empty() or choices.values().has(value):
 			return ""
 		return "%d is none of the values %s declares: %s." % [value, property, _listed(choices)]
+	if hint == PROPERTY_HINT_FLAGS and typeof(value) == TYPE_INT:
+		var flags: Dictionary = flags_of(hint_string)
+		var known: int = 0
+		for bit: int in flags.values():
+			known |= bit
+		var whole: int = value
+		var stray: int = whole & ~known
+		if flags.is_empty() or stray == 0:
+			return ""
+		return (
+			"%d holds bits no flag of %s has (%d): its flags are %s; the engine stores it as given."
+			% [whole, property, stray, _listed(flags)]
+		)
 	if hint != PROPERTY_HINT_RANGE:
 		return ""
 	var parts: PackedStringArray = []
@@ -173,6 +287,20 @@ static func outside(target: Object, declared: Dictionary, value: Variant, shown:
 	)
 
 
+## The flags a flags hint names, each with its bit: "Fill:1,Expand:2" gives its values, and a name
+## with none takes the bit of its place, as @export_flags("A", "B") does.
+static func flags_of(hint_string: String) -> Dictionary:
+	var flags: Dictionary = {}
+	var parts: PackedStringArray = hint_string.split(",", false)
+	for index: int in parts.size():
+		var part: String = parts[index].strip_edges()
+		if ":" in part:
+			flags[part.get_slice(":", 0)] = part.get_slice(":", 1).to_int()
+		else:
+			flags[part] = 1 << index
+	return flags
+
+
 static func _listed(choices: Dictionary) -> String:
 	var listed: PackedStringArray = []
 	for name: String in choices:
@@ -291,3 +419,147 @@ static func is_a(value: Object, name: String) -> bool:
 			return true
 		script = script.get_base_script()
 	return false
+
+
+## Whether writing [param name] on [param target] runs code of its script: the script itself, a
+## property it declares, or any property once it takes sets through [code]_set[/code].
+static func runs_script_code(target: Object, name: String) -> bool:
+	var script: Script = target.get_script()
+	if name == "script":
+		return true
+	if script == null:
+		return false
+	for method: Dictionary in script.get_script_method_list():
+		if str(method.get("name", "")) == "_set":
+			return true
+	for declared: Dictionary in script.get_script_property_list():
+		if str(declared.get("name", "")) == name:
+			return true
+	return false
+
+
+## Why [param property] of a [param holder], an [param engine_class], declared as [param declared],
+## holds [param held], as shown, after it was given [param given], the value and how it is shown. A
+## text property with a list of names holds only one of them, and its getter answers its default
+## for any other. A player's bus is one, though the engine fills its list only in the inspector, so
+## the buses are read from the AudioServer, which holds the project's layout; "the engine changed or
+## refused the value" left a caller to guess the bus did not exist.
+static func not_held(
+	holder: String, engine_class: String, property: String, declared: Dictionary, given: Array, held: String
+) -> String:
+	var value: Variant = given[0]
+	var said: String = "%s.%s was given %s and holds %s after it was set" % [holder, property, given[1], held]
+	var type: int = GdhRead.as_int(declared.get("type", TYPE_NIL))
+	var hint: int = GdhRead.as_int(declared.get("hint", PROPERTY_HINT_NONE))
+	if hint in LAYER_NAMES and typeof(value) == TYPE_INT:
+		return (
+			(
+				"%s: it is a mask of the %s layers, one bit each from layer 1 (1) to layer %d (%d), so it "
+				+ "takes 0 to %d and the engine keeps only those bits. Nothing was written."
+			)
+			% [
+				said,
+				LAYER_NAMES[hint],
+				MASK_LAYERS,
+				1 << (MASK_LAYERS - 1),
+				(1 << MASK_LAYERS) - 1,
+			]
+		)
+	var names: PackedStringArray = []
+	if hint == PROPERTY_HINT_ENUM and (type == TYPE_STRING or type == TYPE_STRING_NAME):
+		names = PackedStringArray(enum_values(str(declared.get("hint_string", ""))).keys())
+	var bus: bool = property == "bus" and engine_class.begins_with("AudioStreamPlayer")
+	if bus:
+		names = []
+		for index: int in AudioServer.bus_count:
+			var _added: bool = names.append(AudioServer.get_bus_name(index))
+	if names.is_empty() or names.has(str(value)):
+		return said + ": the engine changed or refused the value, so nothing was written."
+	var close: PackedStringArray = GdhRead.nearest(str(value), names)
+	var nearest: String = (
+		"%s %s" % ["is" if close.size() == 1 else "are", ", ".join(close)] if not close.is_empty() else ""
+	)
+	if bus:
+		# Not "holds Master after it was set": the getter answers the first bus for any name the
+		# layout lacks, and nothing was kept.
+		return (
+			(
+				"%s.bus takes the name of one of the project's audio buses, and %s is none of them, so it "
+				+ "would play on %s; %s. project_info include audio_buses lists them, and "
+				+ "project_settings add_audio_bus adds one. Nothing was written."
+			)
+			% [
+				holder,
+				given[1],
+				AudioServer.get_bus_name(0),
+				"the buses are " + ", ".join(names) if nearest.is_empty() else "the nearest " + nearest
+			]
+		)
+	return (
+		"%s: it takes one of the names it lists, and %s is none of them; %s. Nothing was written."
+		% [
+			said,
+			given[1],
+			"it lists " + ", ".join(names) if nearest.is_empty() else "the nearest it lists " + nearest
+		]
+	)
+
+
+## The sentence naming the children of [param node] that have [param property], or "" when none
+## does. A property of a helper node set on the body it serves, as navigation_layers on the
+## CharacterBody2D rather than its NavigationAgent2D, was refused with the nearest physics layer.
+static func held_by_children(node: Node, property: String) -> String:
+	var root: Node = node.owner if node.owner != null else node
+	var holders: PackedStringArray = []
+	for child: Node in node.get_children():
+		if property in child:
+			var _added: bool = holders.append("%s (a %s)" % [root.get_path_to(child), child.get_class()])
+	if holders.is_empty():
+		return ""
+	if holders.size() == 1:
+		return " The node at %s has it." % holders[0]
+	var last: String = holders[holders.size() - 1]
+	return " The nodes at %s and %s have it." % [", ".join(holders.slice(0, -1)), last]
+
+
+## A sentence for each node path in [param given], by property, that names no node from
+## [param node]. A path is written whatever it names, as the inspector writes one, since the node may
+## be added next; a joint whose node_a named nothing then joined nothing, and no answer said so.
+static func naming_nothing(node: Node, given: Dictionary) -> Dictionary:
+	var said: Dictionary = {}
+	for property: String in given:
+		if "/" in property or ":" in property:
+			continue
+		# What the node holds, since a path given as text is held as text until the engine stores it.
+		var path: Variant = node.get(property)
+		if not path is NodePath:
+			continue
+		var named: NodePath = path
+		if named.is_empty() or node.get_node_or_null(named) != null:
+			continue
+		said[property] = (
+			(
+				"%s names no node from %s. It is written, as the editor writes one, since that node may "
+				+ "be added next; until it is, %s finds nothing."
+			)
+			% [str(named), node.name, property]
+		)
+	return said
+
+
+## Why [param material] has no [param property]: a ShaderMaterial's parameters are its shader's
+## uniforms, so the shader is what lacks one, and "ShaderMaterial has no property" named the
+## material.
+static func no_uniform(material: ShaderMaterial, property: String) -> String:
+	var uniform: String = property.trim_prefix("shader_parameter/")
+	if material.shader == null:
+		return "The ShaderMaterial has no shader, so it has no parameter %s yet; set shader first." % uniform
+	var shader: String = material.shader.resource_path
+	var named: String = shader if not shader.is_empty() else "Its shader"
+	var uniforms: Array = []
+	for entry: Dictionary in material.shader.get_shader_uniform_list():
+		uniforms.append(str(entry["name"]))
+	var said: String = "%s declares no uniform %s, which %s would set" % [named, uniform, property]
+	if uniforms.is_empty():
+		return said + "; it declares no uniforms."
+	return GdhRead.offered(said, uniform, uniforms) + "."