gdharness 1.3.2 → 1.3.4

package/build/godot/operations/reading.gd

@@ -189,6 +189,21 @@ static func offered(said: String, word: String, names: Array) -> String:
 	return "%s; the nearest it has %s %s" % [said, "is" if close.size() == 1 else "are", ", ".join(close)]
 
 
+## [param said], the refusal for [param property], which [param target] does not declare, with the
+## names it declares nearest it when any are, as a misspelt one is usually one of them. Unlike
+## [method offered], nothing is listed when none is near, since an object declares a hundred.
+static func near_property(said: String, target: Object, property: String) -> String:
+	var headings: int = PROPERTY_USAGE_CATEGORY | PROPERTY_USAGE_GROUP | PROPERTY_USAGE_SUBGROUP
+	var names: Array[String] = []
+	for declared: Dictionary in target.get_property_list():
+		if not as_int(declared.get("usage", 0)) & headings:
+			names.append(str(declared.get("name", "")))
+	var close: PackedStringArray = nearest(property, PackedStringArray(names))
+	if close.is_empty():
+		return said
+	return "%s; the nearest it has %s %s" % [said, "is" if close.size() == 1 else "are", ", ".join(close)]
+
+
 ## The signals [param object] has that a caller can connect, its own class's first: the engine
 ## lists them from Object down, which puts a Button's pressed after thirty a Control has, and names
 ## starting with an underscore are the engine's own.

package/build/godot/operations/same_values.gd

@@ -0,0 +1,177 @@
+@tool
+extends RefCounted
+
+## Whether a value read back is the value that was given, as the tools that write properties judge
+## what a write kept and what it changed besides.
+
+const GdhRead = preload("reading.gd")
+const GdhSerialisation = preload("serialisation.gd")
+
+# The types made of floats, which a read back compares within float precision: a Vector2 property
+# stores 32-bit components, so 0.1 comes back as 0.100000001.
+const FLOAT_SHAPES: Array[int] = [
+	TYPE_VECTOR2,
+	TYPE_VECTOR3,
+	TYPE_VECTOR4,
+	TYPE_QUATERNION,
+	TYPE_COLOR,
+	TYPE_RECT2,
+	TYPE_TRANSFORM2D,
+	TYPE_BASIS,
+	TYPE_TRANSFORM3D,
+	TYPE_PLANE,
+	TYPE_AABB,
+	TYPE_PROJECTION,
+]
+
+const PACKED: Array[int] = [
+	TYPE_PACKED_BYTE_ARRAY,
+	TYPE_PACKED_INT32_ARRAY,
+	TYPE_PACKED_INT64_ARRAY,
+	TYPE_PACKED_FLOAT32_ARRAY,
+	TYPE_PACKED_FLOAT64_ARRAY,
+	TYPE_PACKED_STRING_ARRAY,
+	TYPE_PACKED_VECTOR2_ARRAY,
+	TYPE_PACKED_VECTOR3_ARRAY,
+	TYPE_PACKED_VECTOR4_ARRAY,
+	TYPE_PACKED_COLOR_ARRAY,
+]
+
+# The pairs of built-in resources being compared, so a resource that holds itself ends the
+# comparison instead of recursing into it for ever.
+static var _comparing: Array[Array] = []
+
+
+## Whether [param held] is [param given], as a property read back after a set answers it.
+##
+## Close enough rather than equal for anything made of floats: a Vector2 property stores 32-bit
+## components, so 0.1 comes back as 0.100000001. A packed array read back against the list it was
+## given compares element by element, since `==` between the two is an error rather than false.
+static func same(held: Variant, given: Variant) -> bool:
+	var held_type: int = typeof(held)
+	var given_type: int = typeof(given)
+	# An empty object property reads back as an Object that is null, not as nil, and the two are
+	# the same nothing.
+	var held_none: bool = held_type == TYPE_NIL or (held_type == TYPE_OBJECT and held == null)
+	var given_none: bool = given_type == TYPE_NIL or (given_type == TYPE_OBJECT and given == null)
+	if held_none or given_none:
+		return held_none == given_none
+	if held_type == TYPE_OBJECT or given_type == TYPE_OBJECT:
+		return _same_object(held, given)
+	if GdhSerialisation.NUMBERS.has(held_type) and GdhSerialisation.NUMBERS.has(given_type):
+		if held_type == TYPE_BOOL or given_type == TYPE_BOOL:
+			return held_type == given_type and held == given
+		var held_number: float = GdhRead.as_float(held)
+		var given_number: float = GdhRead.as_float(given)
+		return (is_nan(held_number) and is_nan(given_number)) or is_equal_approx(held_number, given_number)
+	if GdhSerialisation.TEXTS.has(held_type) and GdhSerialisation.TEXTS.has(given_type):
+		return str(held) == str(given)
+	if _listed(held_type) and _listed(given_type):
+		var held_items: Array = type_convert(held, TYPE_ARRAY)
+		var given_items: Array = type_convert(given, TYPE_ARRAY)
+		if held_items.size() != given_items.size():
+			return false
+		for index: int in held_items.size():
+			if not same(held_items[index], given_items[index]):
+				return false
+		return true
+	if held_type == TYPE_DICTIONARY and given_type == TYPE_DICTIONARY:
+		var held_entries: Dictionary = held
+		var given_entries: Dictionary = given
+		return _same_entries(held_entries, given_entries)
+	if held_type != given_type:
+		return false
+	return _same_shape(held, given)
+
+
+static func _same_object(held: Variant, given: Variant) -> bool:
+	if typeof(held) != TYPE_OBJECT or typeof(given) != TYPE_OBJECT:
+		return false
+	if is_same(held, given):
+		return true
+	if not held is Resource or not given is Resource:
+		return false
+	var held_resource: Resource = held
+	var given_resource: Resource = given
+	if not _built_in(held_resource):
+		return held_resource.resource_path == given_resource.resource_path
+	if held_resource.get_class() != given_resource.get_class():
+		return false
+	# A resource local to the scene is duplicated for every instance, so the copy read back is
+	# another object of the same class.
+	if held_resource.resource_local_to_scene:
+		return true
+	return _built_in(given_resource) and _same_stored(held_resource, given_resource)
+
+
+## A resource no other file can refer to: one with no path, or one of a file's own sub-resources,
+## whose path is the file's with "::" and an id after it.
+static func _built_in(resource: Resource) -> bool:
+	return resource.resource_path.is_empty() or resource.resource_path.contains("::")
+
+
+## Two built-in resources of one class, by every property they store. Neither has a path to be
+## known by, and a file loaded again holds a new object for each, so a Curve written into a
+## resource file and read back was judged lost by the save that had just kept it.
+static func _same_stored(held: Resource, given: Resource) -> bool:
+	for pair: Array in _comparing:
+		if is_same(pair[0], held) and is_same(pair[1], given):
+			return true
+	_comparing.append([held, given])
+	var alike: bool = true
+	for property: Dictionary in held.get_property_list():
+		var usage: int = GdhRead.as_int(property.get("usage", 0))
+		var name: String = str(property.get("name", ""))
+		if (
+			not (usage & PROPERTY_USAGE_STORAGE)
+			or (name.begins_with("resource_") and name != "resource_name")
+		):
+			continue
+		if not same(held.get(name), given.get(name)):
+			alike = false
+			break
+	_comparing.pop_back()
+	return alike
+
+
+static func _same_entries(held: Dictionary, given: Dictionary) -> bool:
+	if held.size() != given.size():
+		return false
+	for key: Variant in given:
+		var found: bool = false
+		for held_key: Variant in held:
+			if same(held_key, key):
+				found = same(held[held_key], given[key])
+				break
+		if not found:
+			return false
+	return true
+
+
+## Two values of one type made of floats, compared component by component through the type's own
+## text form, which lists every component: each type has its own is_equal_approx, and reaching it
+## through a Variant is a call the typed gate refuses.
+static func _same_shape(held: Variant, given: Variant) -> bool:
+	if typeof(held) not in FLOAT_SHAPES:
+		return held == given
+	var held_parts: Array[float] = _components(held)
+	var given_parts: Array[float] = _components(given)
+	if held_parts.size() != given_parts.size():
+		return false
+	for index: int in held_parts.size():
+		if not same(held_parts[index], given_parts[index]):
+			return false
+	return true
+
+
+static func _components(value: Variant) -> Array[float]:
+	var parts: Array[float] = []
+	var text: String = var_to_str(value)
+	var inner: String = text.substr(text.find("(") + 1).trim_suffix(")")
+	for part: String in inner.split(",", false):
+		parts.append(part.strip_edges().to_float())
+	return parts
+
+
+static func _listed(type: int) -> bool:
+	return type == TYPE_ARRAY or PACKED.has(type)

package/build/godot/operations/serialisation.gd

@@ -121,6 +121,10 @@ const BUILDERS: Dictionary = {
 	"Dictionary": "_build_dictionary",
 }
 
+## The built-in resources being described, outermost first, so one holding itself somewhere inside
+## is answered by its class rather than without end.
+var _describing: Array[Resource] = []
+
 
 # Converts a Godot value into something JSON can carry. A type with no entry in the table
 # passes through as itself, which is what the JSON-native ones want.
@@ -665,9 +669,21 @@ func _serialize_object(value: Object) -> Variant:
 		return _describe_input_event(event)
 	if value is Resource:
 		var resource: Resource = value
-		if resource.resource_path.is_empty():
-			return {"class": resource.get_class(), "_type": "Resource"}
-		return {"path": resource.resource_path, "class": resource.get_class(), "_type": "Resource"}
+		# A file's built-in resources load with a path of the file's own and "::", which no other
+		# file can refer to.
+		if resource.resource_path.is_empty() or resource.resource_path.contains("::"):
+			return _describe_built_in(resource)
+		var filed: Dictionary = {
+			"path": resource.resource_path, "class": resource.get_class(), "_type": "Resource"
+		}
+		# The engine class of a resource with a script is the one its script extends, so a Stats
+		# file read as a Resource and nothing said it was a Stats.
+		var attached: Variant = resource.get_script()
+		if attached is Script:
+			var script: Script = attached
+			if not script.get_global_name().is_empty():
+				filed["scriptClass"] = str(script.get_global_name())
+		return filed
 	if value is Node:
 		var node: Node = value
 		if node.is_inside_tree():
@@ -675,6 +691,62 @@ func _serialize_object(value: Object) -> Variant:
 	return _describe_object(value)
 
 
+## A resource built into the file it was read from, in the form a write builds one from: its class
+## under _type beside every property it stores away from its default. As its class alone it said
+## nothing of what it held, so a CollisionShape2D's radius could not be read, and it could not be
+## written back.
+func _describe_built_in(resource: Resource) -> Dictionary:
+	if _describing.has(resource):
+		return {"class": resource.get_class(), "_type": "Resource"}
+	_describing.append(resource)
+	var described: Dictionary = {"_type": resource.get_class()}
+	var attached: Variant = resource.get_script()
+	var script: Script = null
+	if attached is Script:
+		script = attached
+		described["script"] = serialize_value(script)
+	var fresh: Object = _fresh(script)
+	for property: Dictionary in resource.get_property_list():
+		var usage: int = property.get("usage", 0)
+		var name: String = str(property.get("name", ""))
+		if (
+			not (usage & PROPERTY_USAGE_STORAGE)
+			or name == "script"
+			or (name.begins_with("resource_") and name != "resource_name")
+		):
+			continue
+		var held: Variant = resource.get(name)
+		var default: Variant = ClassDB.class_get_property_default_value(resource.get_class(), name)
+		if fresh != null:
+			default = fresh.get(name)
+		elif script != null and usage & PROPERTY_USAGE_SCRIPT_VARIABLE:
+			default = script.get_property_default_value(name)
+		if typeof(held) == typeof(default) and held == default:
+			continue
+		described[name] = serialize_value(held)
+	_describing.pop_back()
+	return described
+
+
+## A new instance of [param script] to read defaults off, or null where none should be made. What
+## the script's own code sets as it is made (a resource_name in _init, a list built by a
+## constructor, which the engine reports no default for) is then a default rather than a value
+## the file holds. None is made for a script whose _init needs arguments, nor in the editor for one
+## that is not a tool: the editor never runs those, and can_instantiate says so.
+static func _fresh(script: Script) -> Object:
+	if script == null or not script.can_instantiate():
+		return null
+	for method: Dictionary in script.get_script_method_list():
+		if str(method.get("name", "")) == "_init":
+			var arguments: Array = method.get("args", [])
+			var defaults: Array = method.get("default_args", [])
+			if arguments.size() > defaults.size():
+				return null
+	# Called by name: new() is declared on each kind of script rather than on Script.
+	var made: Variant = script.call("new")
+	return made if made is Object else null
+
+
 ## An input event, by what it is bound to: the engine's own words for it and every field it stores
 ## away from its default. As a bare resource it was its class and nothing else, so an input action
 ## read back from project.godot could not say whether it was bound to Space or to a joypad button.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdharness",
-  "version": "1.3.2",
+  "version": "1.3.4",
   "mcpName": "io.github.Aureliolo/gdharness",
   "description": "A harness for driving a Godot 4 project from an agent: editor addons, a runtime bridge into the running game, an MCP server in front of them, and a CLI that installs and diagnoses the Godot side.",
   "type": "module",