gdharness 0.13.2 → 0.13.4

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

@@ -2,46 +2,47 @@ extends RefCounted
 
 ## What crosses the wire between the game and the server, in both directions: Godot values
 ## as JSON-safe dictionaries, and JSON back into the values a property or parameter wants.
+##
+## The conversion itself is the shared one, so a value read off a running game is spelled exactly
+## as the same value read off the editor or off a headless engine. What is here is the part that is
+## only true of a running game: reaching a node by path, and fitting an argument to the type the
+## method it is going to declares.
 
 const Read = preload("reading.gd")
-
-# What each Godot type becomes on the wire, keyed on typeof() rather than written as a chain of
-# `is` tests whose order has to be trusted: Resource had to be tested before Object, or every
-# resource came back as a bare class name with its path dropped.
-#
-# Method names rather than Callables or lambdas: a lambda spanning more than one line inside a
-# dictionary literal is where gdformat loses track of every comment in the file and writes them
-# all again into the lambda body, on every run.
-const SERIALISERS: Dictionary = {
-	TYPE_NIL: "_serialize_nil",
-	TYPE_VECTOR2: "_serialize_vector2",
-	TYPE_VECTOR3: "_serialize_vector3",
-	TYPE_VECTOR2I: "_serialize_vector2i",
-	TYPE_VECTOR3I: "_serialize_vector3i",
-	TYPE_COLOR: "_serialize_color",
-	TYPE_NODE_PATH: "_serialize_node_path",
-	TYPE_ARRAY: "_serialize_array",
-	TYPE_RECT2: "_serialize_rect2",
-	TYPE_TRANSFORM2D: "_serialize_transform2d",
-	TYPE_DICTIONARY: "_serialize_dictionary",
-	TYPE_OBJECT: "_serialize_object",
-}
-
-
-## 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.
-##
-## A method or property typed as a class answers a null with a Variant of type OBJECT that has
-## nothing behind it, and so does one whose object has been freed. Asking either for its class is
-## a script error, and a script error here costs far more than the one answer: the request is
-## never replied to at all, and an editor playing the game stops it dead on the error, so every
-## question after it times out as well. `find_child` for a name nothing has cost a whole session
-## that way.
+const Serialisation = preload("serialisation.gd")
+
+# What the engine carries from one to another without complaint, which is what an argument may
+# arrive as. Numbers include bool because the engine counts it as one, and the three text types
+# are one string wearing three hats.
+const NUMBERS: Array[int] = [TYPE_BOOL, TYPE_INT, TYPE_FLOAT]
+const TEXTS: Array[int] = [TYPE_STRING, TYPE_STRING_NAME, TYPE_NODE_PATH]
+
+# The types that cross as a plain JSON list and have to be built back into themselves. A list is
+# what a caller can write by hand and what the serialiser answers with, and the parameter or
+# property being written is the only thing that knows which of these it wanted.
+const LIST_TYPES: Array[int] = [
+	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,
+]
+
+var _shared: Serialisation = Serialisation.new()
+
+
+## Converts a Godot value into something JSON can carry.
 func serialize(value: Variant) -> Variant:
-	if typeof(value) == TYPE_OBJECT and not is_instance_valid(value):
-		return null
-	var serialiser: String = SERIALISERS.get(typeof(value), "")
-	return call(serialiser, value) if not serialiser.is_empty() else value
+	return _shared.serialize_value(value)
+
+
+## Rebuilds a Godot value from the shape [method serialize] gave it.
+func deserialize(value: Variant) -> Variant:
+	return _shared.deserialize_value(value)
 
 
 ## The node [param path] names under [param root], or a refusal saying why there is not one.
@@ -75,148 +76,50 @@ static func node_at(root: Node, path: String) -> Dictionary:
 	return {"node": node}
 
 
-func _serialize_nil(_value: Variant) -> Variant:
-	return null
-
-
-func _serialize_vector2(value: Vector2) -> Dictionary:
-	return {"_type": "Vector2", "x": value.x, "y": value.y}
-
-
-func _serialize_vector3(value: Vector3) -> Dictionary:
-	return {"_type": "Vector3", "x": value.x, "y": value.y, "z": value.z}
-
-
-func _serialize_vector2i(value: Vector2i) -> Dictionary:
-	return {"_type": "Vector2i", "x": value.x, "y": value.y}
-
-
-func _serialize_vector3i(value: Vector3i) -> Dictionary:
-	return {"_type": "Vector3i", "x": value.x, "y": value.y, "z": value.z}
-
-
-func _serialize_color(value: Color) -> Dictionary:
-	return {"_type": "Color", "r": value.r, "g": value.g, "b": value.b, "a": value.a}
-
-
-func _serialize_node_path(value: NodePath) -> Dictionary:
-	return {"_type": "NodePath", "path": str(value)}
-
-
-func _serialize_array(value: Array) -> Array:
-	return value.map(serialize)
-
-
-func _serialize_rect2(value: Rect2) -> Dictionary:
-	return {"_type": "Rect2", "position": serialize(value.position), "size": serialize(value.size)}
-
-
-func _serialize_transform2d(value: Transform2D) -> Dictionary:
-	return {
-		"_type": "Transform2D",
-		"origin": serialize(value.origin),
-		"x": serialize(value.x),
-		"y": serialize(value.y)
-	}
-
-
-func _serialize_dictionary(value: Dictionary) -> Dictionary:
-	var serialised: Dictionary = {}
-	for key: Variant in value:
-		serialised[str(key)] = serialize(value[key])
-	return serialised
-
-
-## The one case that genuinely needs the class hierarchy, since a Resource is also an Object and
-## its path is the half worth having. A node in the tree is answered with its path, so a
-## property that points at one can be fed straight back to any tool that takes a node.
-func _serialize_object(value: Object) -> Dictionary:
-	if value is Resource:
-		var resource: Resource = value
-		return {"_type": "Resource", "path": resource.resource_path, "class": resource.get_class()}
-	if value is Node:
-		var node: Node = value
-		if node.is_inside_tree():
-			return {"_type": "Node", "class": node.get_class(), "path": str(node.get_path())}
-	return _describe_object(value)
-
-
-## A plain object, said in enough detail to tell it from the one beside it.
+## Whether two values can be compared without the comparison itself failing.
 ##
-## `{"class": "RefCounted"}` was all of it, so a roster of twelve people came back as the word
-## RefCounted twelve times: correct, useless, and indistinguishable from a list of twelve of
-## anything else. The state worth looking at in a game is lists of these, so each one carries what
-## it is (the `class_name` its script declares, or the script's path when it has no name), what it
-## says about itself when the game has given it a `_to_string`, and an id that is at least
-## different per object. None of it is invented: every field is left out when there is nothing to
-## put in it, because a key holding "" is a worse answer than a key that is not there.
-func _describe_object(value: Object) -> Dictionary:
-	var described: Dictionary = {"_type": "Object", "class": value.get_class()}
-	# Asked as a Variant and narrowed, because get_script answers one and an object without a
-	# script answers null: casting that to Script is the unsafe cast the engine refuses to compile.
-	var attached: Variant = value.get_script()
-	if attached is Script:
-		var script: Script = attached
-		var declared: String = String(script.get_global_name())
-		if not declared.is_empty():
-			described["script_class"] = declared
-		elif not script.resource_path.is_empty():
-			described["script"] = script.resource_path
-	# Only when the game wrote one. The default is "<RefCounted#31098236>", which is the id again
-	# in a costume and reads as if the object had been asked and had nothing to say.
-	if value.has_method("_to_string"):
-		described["says"] = value.to_string()
-	described["id"] = value.get_instance_id()
-	return described
-
-
-## Rebuilds a Godot value from the shape serialize gave it.
-func deserialize(value: Variant) -> Variant:
-	if value == null:
-		return null
-	if value is Array:
-		var items: Array = value
-		var rebuilt: Array = []
-		for item: Variant in items:
-			rebuilt.append(deserialize(item))
-		return rebuilt
-	if not value is Dictionary:
-		return value
-
-	var fields: Dictionary = value
-	if not fields.has("_type"):
-		var rebuilt: Dictionary = {}
-		for key: Variant in fields:
-			rebuilt[key] = deserialize(fields[key])
-		return rebuilt
-
-	match fields["_type"]:
-		"Vector2":
-			return Vector2(Read.as_float(fields.get("x", 0)), Read.as_float(fields.get("y", 0)))
-		"Vector3":
-			return Vector3(
-				Read.as_float(fields.get("x", 0)),
-				Read.as_float(fields.get("y", 0)),
-				Read.as_float(fields.get("z", 0))
-			)
-		"Vector2i":
-			return Vector2i(Read.as_int(fields.get("x", 0)), Read.as_int(fields.get("y", 0)))
-		"Vector3i":
-			return Vector3i(
-				Read.as_int(fields.get("x", 0)),
-				Read.as_int(fields.get("y", 0)),
-				Read.as_int(fields.get("z", 0))
-			)
-		"Color":
-			return Color(
-				Read.as_float(fields.get("r", 0)),
-				Read.as_float(fields.get("g", 0)),
-				Read.as_float(fields.get("b", 0)),
-				Read.as_float(fields.get("a", 1), 1.0)
-			)
-		"NodePath":
-			return NodePath(str(fields.get("path", "")))
-	return value
+## GDScript's `==` is not total. An Object against a String is a hard error rather than false, and
+## an error raised inside the game is not a wrong answer: it stops the game. A caller who asked
+## `runtime_wait until` for the wrong kind of value got their game held at a debugger break, every
+## later call answering "did not respond within 10000ms, it may be stuck in a long frame", and
+## nothing anywhere naming the argument that did it. A wrong argument costs a refusal, never the
+## session's game.
+##
+## Only an object is special. Every other pair the engine answers, false where they differ, and
+## refusing those would refuse calls that work: an int against a float is the same number to a
+## caller waiting for 1 on a property holding 1.0.
+static func comparable(one: Variant, other: Variant) -> bool:
+	var left: int = typeof(one)
+	var right: int = typeof(other)
+	if left != TYPE_OBJECT and right != TYPE_OBJECT:
+		return true
+	# An object compares with another object and with null. Anything else is the error above.
+	return (left == TYPE_OBJECT or left == TYPE_NIL) and (right == TYPE_OBJECT or right == TYPE_NIL)
+
+
+## Whether a value can be handed to a parameter declared as [param type] without the call failing.
+##
+## The same reason as [method comparable]: `callv` raises inside the game when an argument cannot
+## be converted, and an error raised in a game somebody is playing holds it at a debugger break.
+##
+## A list of what is accepted rather than of what is refused, which is the way round that errs
+## safely. The engine's own conversion table is not readable from GDScript, so either list is a
+## guess at it; guessing narrow costs a caller a refusal naming both types, and guessing wide costs
+## them the session. A refusal is the cheaper mistake, and it is the one they can act on.
+static func acceptable(value: Variant, type: int) -> bool:
+	if type == TYPE_NIL:
+		return true
+	var given: int = typeof(value)
+	if given == type:
+		return true
+	# null is a value for anything that holds an object, and for nothing else.
+	if given == TYPE_NIL:
+		return type == TYPE_OBJECT
+	if NUMBERS.has(given) and NUMBERS.has(type):
+		return true
+	if TEXTS.has(given) and TEXTS.has(type):
+		return true
+	return given == TYPE_ARRAY and LIST_TYPES.has(type)
 
 
 ## The declared type of one parameter of a method, or TYPE_NIL when the method or the parameter
@@ -236,11 +139,18 @@ func parameter_type(object: Object, method: String, index: int) -> int:
 ## A value from the wire fitted to the type a property or parameter declares. Arguments arrive
 ## as strings often enough, and callv refuses a "2.0" where a float is wanted, so a string that
 ## reads as the wanted scalar is read as one.
+##
+## The conversion is also what restores a packed array's exact type. Those cross as the plain JSON
+## lists they fit into, so what comes back from the wire is an Array, and the parameter is what says
+## it was a PackedStringArray.
 func fitted(value: Variant, type: int) -> Variant:
 	var rebuilt: Variant = deserialize(value)
 	if type == TYPE_NIL or typeof(rebuilt) == type:
 		return rebuilt
 
+	if rebuilt is Array and LIST_TYPES.has(type):
+		return type_convert(rebuilt, type)
+
 	var simple: Array[int] = [TYPE_BOOL, TYPE_INT, TYPE_FLOAT, TYPE_STRING]
 	if not simple.has(type) or not simple.has(typeof(rebuilt)):
 		return rebuilt

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

@@ -108,8 +108,31 @@ func wait_until(params: Dictionary) -> Dictionary:
 
 	var current: Variant = node.get(property)
 	var wanted: Variant = _values.fitted(params["value"], typeof(current))
+	# Refused before anything is evaluated, because the evaluation is what does the damage: an
+	# object compared against anything else is a hard error in GDScript, raised inside the game,
+	# which holds it at a debugger break. Both types are named because the caller cannot see either
+	# from where they are standing.
+	if not Values.comparable(current, wanted):
+		return {
+			"type": "error",
+			"message":
+			(
+				(
+					"%s.%s holds %s and the value to wait for is %s. Those cannot be compared, and"
+					+ " waiting on it would stop the game rather than answer about it."
+				)
+				% [node_path, property, type_string(typeof(current)), type_string(typeof(wanted))]
+			)
+		}
+
 	var started: int = Time.get_ticks_msec()
-	while current != wanted and Time.get_ticks_msec() - started < timeout_ms:
+	# The type is checked every time round, not only at the top: a property that holds an object a
+	# frame later is the same error arriving late.
+	while (
+		Values.comparable(current, wanted)
+		and current != wanted
+		and Time.get_ticks_msec() - started < timeout_ms
+	):
 		await _host.get_tree().process_frame
 		if not is_instance_valid(node):
 			return {"type": "error", "message": "%s was freed while waiting" % node_path}
@@ -119,7 +142,7 @@ func wait_until(params: Dictionary) -> Dictionary:
 		"type": "condition",
 		"path": node_path,
 		"property": property,
-		"met": current == wanted,
+		"met": Values.comparable(current, wanted) and current == wanted,
 		"value": _values.serialize(current),
 		"elapsed_ms": Time.get_ticks_msec() - started,
 	}