gdharness 1.2.28 → 1.2.30

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

@@ -11,6 +11,25 @@ extends RefCounted
 const Read = preload("reading.gd")
 const Serialisation = preload("serialisation.gd")
 
+## The engine singletons a call, a write or a read may name instead of a node: what the engine
+## measures, and the engine settings that are the game's own. Not every singleton: OS runs programs
+## and opens files, DisplayServer switches the keyboard's layout and Input moves the real pointer,
+## and none of that is a game's to do to the machine it runs on.
+const SINGLETONS: Array[String] = [
+	"Engine",
+	"Performance",
+	"RenderingServer",
+	"AudioServer",
+	"PhysicsServer2D",
+	"PhysicsServer3D",
+	"NavigationServer2D",
+	"NavigationServer3D",
+	"Time",
+	"TranslationServer",
+]
+## The most frames a press is held in one call, as many as a frames wait takes.
+const MOST_HELD: int = 600
+
 var _shared: Serialisation = Serialisation.new()
 
 
@@ -55,6 +74,56 @@ static func node_at(root: Node, path: String) -> Dictionary:
 	return {"node": node}
 
 
+## How many process frames a whole press holds before its release, from `holdFrames`: one unless
+## asked, as the halves of a press have always been a frame apart. Held inside the game because the
+## time between a press, a wait and a release sent as three calls counts as held too: a 60-frame
+## pour poured for nearly three seconds. A String saying why, where the hold cannot be.
+static func held_for(params: Dictionary) -> Variant:
+	if not params.has("holdFrames"):
+		return 1
+	if params.has("pressed"):
+		return (
+			"holdFrames holds a whole press and then lets go, and pressed asks for one half of one:"
+			+ " give one or the other."
+		)
+	var frames: int = Read.as_int(params["holdFrames"], 0)
+	if frames < 1 or frames > MOST_HELD:
+		return "holdFrames is %d, and it takes 1 to %d." % [frames, MOST_HELD]
+	return frames
+
+
+## What a press says it was held for: [param frames] for a whole one, nothing for one half.
+static func held_answer(whole: bool, frames: int) -> Variant:
+	if whole:
+		return frames
+	return null
+
+
+## What [param path] names: a node under [param root], as [method node_at] reads it, or an engine
+## singleton by its name. Answers the object under "object", and under "node" the node that objects
+## named in a value are found from, which for a singleton is [param root].
+static func target_at(root: Node, path: String) -> Dictionary:
+	if SINGLETONS.has(path):
+		return {"object": Engine.get_singleton(path), "node": root}
+	if not path.contains("/") and Engine.has_singleton(path):
+		return {
+			"type": "error",
+			"message":
+			(
+				(
+					"%s is an engine singleton, and the ones that can be reached are %s. The rest act"
+					+ " on the machine rather than the game: OS runs programs, DisplayServer switches the"
+					+ " keyboard's layout and Input moves the real pointer."
+				)
+				% [path, ", ".join(SINGLETONS)]
+			),
+		}
+	var standing: Dictionary = node_at(root, path)
+	if standing.has("message"):
+		return standing
+	return {"object": standing["node"], "node": standing["node"]}
+
+
 ## Whether two values can be compared without the comparison itself failing.
 static func comparable(one: Variant, other: Variant) -> bool:
 	return Serialisation.comparable(one, other)
@@ -65,6 +134,28 @@ static func acceptable(value: Variant, type: int) -> bool:
 	return Serialisation.acceptable(value, type)
 
 
+## Whether [param given] would have to be cut to become a [param type]: a fraction made a whole
+## number, or a number other than 0 or 1 made a truth.
+##
+## A number arrives from JSON as a float, so one is converted to what the slot holds, and the
+## conversion truncates: 2.5 written into an int was stored as 2 and answered as written, and 0.2 on
+## a bool became true. A number written as text counts as the number.
+static func cuts(given: Variant, type: int) -> bool:
+	if type != TYPE_INT and type != TYPE_BOOL:
+		return false
+	var number: Variant = given
+	if given is String:
+		var text: String = given
+		number = Read.json_or_null(text)
+	if typeof(number) != TYPE_FLOAT and typeof(number) != TYPE_INT:
+		return false
+	var value: float = Read.as_float(number)
+	var whole: bool = value == floorf(value)
+	if type == TYPE_INT:
+		return not whole
+	return not (whole and (value == 0.0 or value == 1.0))
+
+
 ## How a value of [param type] is written to be read as one, or empty when it is not built from fields.
 static func written_as(type: int) -> String:
 	return Serialisation.written_as(type)
@@ -98,6 +189,52 @@ func parameter_class(object: Object, method: String, index: int) -> String:
 	return ""
 
 
+## The components a path reads off [param value], by the names GDScript gives them, or none for a
+## value that has none: a vector's axes, a colour's channels, a rectangle's corners and size, a
+## transform's basis and origin. A value of one of these is a copy wherever it is read, so a write
+## into a component is a write into the copy until it is put back where it was read from.
+static func components_of(value: Variant) -> PackedStringArray:
+	match typeof(value):
+		TYPE_VECTOR2, TYPE_VECTOR2I:
+			return PackedStringArray(["x", "y"])
+		TYPE_VECTOR3, TYPE_VECTOR3I:
+			return PackedStringArray(["x", "y", "z"])
+		TYPE_VECTOR4, TYPE_VECTOR4I, TYPE_QUATERNION:
+			return PackedStringArray(["x", "y", "z", "w"])
+		TYPE_COLOR:
+			return PackedStringArray(
+				[
+					"r",
+					"g",
+					"b",
+					"a",
+					"r8",
+					"g8",
+					"b8",
+					"a8",
+					"h",
+					"s",
+					"v",
+					"ok_hsl_h",
+					"ok_hsl_s",
+					"ok_hsl_l"
+				]
+			)
+		TYPE_RECT2, TYPE_RECT2I, TYPE_AABB:
+			return PackedStringArray(["position", "size", "end"])
+		TYPE_PLANE:
+			return PackedStringArray(["normal", "x", "y", "z", "d"])
+		TYPE_BASIS:
+			return PackedStringArray(["x", "y", "z"])
+		TYPE_TRANSFORM2D:
+			return PackedStringArray(["x", "y", "origin"])
+		TYPE_TRANSFORM3D:
+			return PackedStringArray(["basis", "origin"])
+		TYPE_PROJECTION:
+			return PackedStringArray(["x", "y", "z", "w"])
+	return PackedStringArray()
+
+
 ## What the slot [param named] on [param holder] declares it holds, as `{"type": int, "class":
 ## String, "script": Script or null}`: a property's declaration, or the element type of a typed list
 ## or the value type of a typed map. TYPE_NIL when nothing is declared, which is also what a
@@ -111,6 +248,11 @@ func parameter_class(object: Object, method: String, index: int) -> String:
 ## as a script class with no `class_name` is declared under the engine class the script extends,
 ## measured on 4.7.2: `var quarrel: Walker` with Walker a preloaded Node3D script lists as Node3D.
 static func slot_declared(holder: Variant, named: String) -> Dictionary:
+	# A component holds one kind of value and no other: a vector's axis is a number, its integer
+	# form's an integer, a rectangle's size a vector of the same form.
+	if named in components_of(holder):
+		var component: Variant = holder[named]
+		return {"type": typeof(component), "class": "", "script": null}
 	if holder is Array:
 		var items: Array = holder
 		if items.is_typed():

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

@@ -312,19 +312,7 @@ static func _in_order(compare: String, limit: float, current: Variant) -> bool:
 ## conversion truncates: 3.5 waited on an int became 3 and 0.2 on a bool became true, and a property
 ## already holding that answered met at once, about a state nobody asked for.
 static func _cut_to_fit(given: Variant, type: int, node_path: String, property: String) -> String:
-	if type != TYPE_INT and type != TYPE_BOOL:
-		return ""
-	var number: Variant = given
-	if given is String:
-		var text: String = given
-		number = Read.json_or_null(text)
-	if typeof(number) != TYPE_FLOAT and typeof(number) != TYPE_INT:
-		return ""
-	var value: float = Read.as_float(number)
-	var whole: bool = value == floorf(value)
-	if type == TYPE_INT and whole:
-		return ""
-	if type == TYPE_BOOL and whole and (value == 0.0 or value == 1.0):
+	if not Values.cuts(given, type):
 		return ""
 	return (
 		(