gdharness 1.2.27 → 1.2.29

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

@@ -93,23 +93,37 @@ const READS_ONLY: String = ", and a path, which a wait reads every frame, only c
 ## "get_theme_stylebox(\"panel\"):content_margin_top", since what a control's theme gives it is only
 ## reachable by naming what is asked for; see [method arguments_of].
 ##
+## A step into a vector, a colour, a rectangle or a transform reads one of its components,
+## "size:x" or "global_transform:origin:y", by the names GDScript gives them; see
+## [method Values.components_of].
+##
 ## Answers with a `message` instead when a step along the way is not there or holds something that
 ## is not an object, naming the step rather than the whole path: "/root/Main:_game has no property
-## clocks" is a typo found, and "no property _game:clocks:speed" is a puzzle.
-static func walk_to(node: Node, node_path: String, reaching: String) -> Dictionary:
+## clocks" is a typo found, and "no property _game:clocks:speed" is a puzzle. Answers `chain` as
+## well, each holder walked through and the step taken off it, for [method write_back].
+static func walk_to(node: Object, node_path: String, reaching: String) -> Dictionary:
 	var parts: PackedStringArray = steps_of(reaching)
 	var holder: Variant = node
 	var called: String = node_path
+	var chain: Array[Dictionary] = []
 	for step: int in parts.size() - 1:
 		var named: String = parts[step]
 		if not can_read(holder, named):
 			return {"type": "error", "message": nothing_there(holder, named, called)}
+		chain.append({"holder": holder, "named": named, "called": called})
 		holder = read_under(holder, named)
 		called = "%s:%s" % [called, named]
-		if not _can_hold(holder):
+		if not can_hold(holder):
 			var wanted: String = parts[step + 1]
-			return {"type": "error", "message": "%s holds no object to read %s off" % [called, wanted]}
-	return {"holder": holder, "name": parts[parts.size() - 1], "called": called}
+			return {
+				"type": "error",
+				"message":
+				(
+					"%s holds %s, which has nothing to read %s off"
+					% [called, type_string(typeof(holder)), wanted]
+				)
+			}
+	return {"holder": holder, "name": parts[parts.size() - 1], "called": called, "chain": chain}
 
 
 ## The object [param given] names for a method's argument, as `{"object": ...}`, or as
@@ -160,10 +174,17 @@ static func object_at(root: Node, node: Node, node_path: String, given: Variant)
 	return {"object": value}
 
 
-## Whether a step can be taken into [param value] at all: an object, a list or a map can be walked
-## into, and a number or a string is where a path ends whether the caller meant it to or not.
-static func _can_hold(value: Variant) -> bool:
-	return value is Object or value is Array or value is Dictionary or packed(value)
+## Whether a step can be taken into [param value] at all: an object, a list, a map or a value with
+## components can be walked into, and a number or a string is where a path ends whether the caller
+## meant it to or not.
+static func can_hold(value: Variant) -> bool:
+	return value is Object or value is Array or value is Dictionary or packed(value) or composite(value)
+
+
+## Whether [param value] is read by its components, a vector or a colour or a transform, and is a
+## copy wherever it is read from.
+static func composite(value: Variant) -> bool:
+	return not Values.components_of(value).is_empty()
 
 
 ## Whether [param value] is a packed list. Stepped into the way a list is, by index, and a write into
@@ -212,6 +233,8 @@ static func can_read(holder: Variant, named: String) -> bool:
 		if not method.is_empty():
 			return args.is_empty() and method in MAP_CALLS
 		return not _key_in(map, named).is_empty()
+	if composite(holder):
+		return method.is_empty() and named in Values.components_of(holder)
 	if holder is Object:
 		var object: Object = holder
 		if not method.is_empty():
@@ -420,25 +443,62 @@ static func _native_flags(object: Object, method: String) -> int:
 	return 0
 
 
-## Put [param value] where [param named] points. Only ever called once [method can_read] agrees,
-## and lists and maps are reference types, so writing into one reaches the game's own copy.
-static func write(holder: Variant, named: String, value: Variant) -> void:
+## Put [param value] where [param named] points, and answer the holder written into. Only ever
+## called once [method can_read] agrees. Lists and maps are reference types, so writing into one
+## reaches the game's own copy; a vector or a transform is a copy, and the one answered is the
+## changed copy, for [method write_back] to put where it came from.
+static func write(holder: Variant, named: String, value: Variant) -> Variant:
 	if holder is Array:
 		var items: Array = holder
 		items[_index_in(named, items.size())] = value
-		return
+		return holder
 	if packed(holder):
 		var list: Variant = holder
 		list[_index_in(named, len(holder))] = value
-		return
+		return holder
 	if holder is Dictionary:
 		var map: Dictionary = holder
 		# Written back under the key it was found under, since a map keyed by StringName and one
 		# keyed by String both read the same way and a write to the wrong one adds a second entry.
 		map[_key_in(map, named)[0]] = value
-		return
+		return holder
+	if composite(holder):
+		var changed: Variant = holder
+		changed[named] = value
+		return changed
 	var object: Object = holder
 	object.set(named, value)
+	return holder
+
+
+## Why a write into [param chain]'s last holder, a copy, cannot reach the game, or "" when it can:
+## each copy is put back where it was read from on the way up, and a step that was a call answered
+## a copy the game does not keep anywhere. [param chain] is the one [method walk_to] answered.
+static func unwritable_copy(chain: Array[Dictionary]) -> String:
+	for index: int in range(chain.size() - 1, -1, -1):
+		var link: Dictionary = chain[index]
+		var named: String = link["named"]
+		if not method_of(named).is_empty():
+			return (
+				"%s:%s is what a call answered, a copy the game keeps nowhere, so a part of it is not a place to write"
+				% [link["called"], named]
+			)
+		if not composite(link["holder"]):
+			return ""
+	return ""
+
+
+## Puts [param changed], the copy a write into a vector or a transform changed, back where
+## [param chain] read it from, and every copy it was read out of back where that came from, up to
+## the first holder keeping its own: an object, whose setter runs, a list or a map.
+static func write_back(chain: Array[Dictionary], changed: Variant) -> void:
+	var value: Variant = changed
+	for index: int in range(chain.size() - 1, -1, -1):
+		var link: Dictionary = chain[index]
+		var holder: Variant = link["holder"]
+		value = write(holder, str(link["named"]), value)
+		if not composite(holder):
+			return
 
 
 ## What [param holder] holds under [param named], or answers to it when [param named] is a call.
@@ -455,6 +515,8 @@ static func read_under(holder: Variant, named: String) -> Variant:
 	if holder is Dictionary:
 		var map: Dictionary = holder
 		return map[_key_in(map, named)[0]]
+	if composite(holder):
+		return holder[named]
 	var object: Object = holder
 	var method: String = method_of(named)
 	if not method.is_empty():
@@ -521,6 +583,18 @@ static func nothing_there(holder: Variant, named: String, called_as: String) ->
 		if keys.size() > 8:
 			rest = " and %d more" % [keys.size() - 8]
 		return "%s has no key %s; it is keyed by %s%s" % [called_as, named, ", ".join(some), rest]
+	if composite(holder):
+		var kind: String = type_string(typeof(holder))
+		var sort: String = ("an " if kind.left(1) in ["A", "E", "I", "O", "U"] else "a ") + kind
+		var has: String = ", ".join(Values.components_of(holder))
+		if not container_call.is_empty():
+			return (
+				"%s is %s, which a path reads by its components, %s, and makes no call on"
+				% [called_as, sort, has]
+			)
+		return "%s is %s, so it has no %s; it has %s" % [called_as, sort, named, has]
+	if not holder is Object:
+		return "%s is %s, which has nothing to read %s off" % [called_as, type_string(typeof(holder)), named]
 	var object: Object = holder
 	var method: String = method_of(named)
 	if not method.is_empty():

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

@@ -35,7 +35,10 @@ var _host: Node
 var _values: Values
 ## How long each of the last frames took, oldest first, in microseconds, as the game timed them.
 var _frame_usec: PackedInt64Array = PackedInt64Array()
+## How many physics steps ran in each of those frames, in the same order.
+var _frame_physics: PackedInt64Array = PackedInt64Array()
 var _last_frame_usec: int = 0
+var _last_physics_frames: int = 0
 
 
 ## The host is the autoload, which is how the tree is reached: it is not in one when the
@@ -631,12 +634,12 @@ func get_property(params: Dictionary) -> Dictionary:
 	if node_path.is_empty() or property.is_empty():
 		return {"type": "error", "message": "Node path and property required"}
 
-	var standing: Dictionary = Values.node_at(_host.get_tree().root, node_path)
+	var standing: Dictionary = Values.target_at(_host.get_tree().root, node_path)
 	if standing.has("message"):
 		return standing
-	var node: Node = standing["node"]
+	var target: Object = standing["object"]
 
-	var reached: Dictionary = Paths.walk_to(node, node_path, property)
+	var reached: Dictionary = Paths.walk_to(target, node_path, property)
 	if reached.has("message"):
 		return reached
 
@@ -662,12 +665,21 @@ func get_property(params: Dictionary) -> Dictionary:
 ## read 45ms for a second at a time, and a change to the game showed only on the next second's
 ## worst frame. The time between two of these calls is the frame as it passed, physics and the wait
 ## for the display included.
+##
+## The physics steps are counted beside it because the engine steps physics from the wall clock and
+## nothing else reports how many it took: a game drawing sixty frames a second whose brew advanced
+## by physics steps moved a tenth as far as the frames promised, and every reading available said
+## the game was running well.
 func note_frame(now_usec: int) -> void:
+	var physics: int = Engine.get_physics_frames()
 	if _last_frame_usec > 0:
 		var _grew: bool = _frame_usec.push_back(now_usec - _last_frame_usec)
+		var _stepped: bool = _frame_physics.push_back(physics - _last_physics_frames)
 		if _frame_usec.size() > FRAMES_TIMED:
 			_frame_usec.remove_at(0)
+			_frame_physics.remove_at(0)
 	_last_frame_usec = now_usec
+	_last_physics_frames = physics
 
 
 ## Whether the frame waits for the display, which sets its floor: a game with vsync on cannot
@@ -695,16 +707,26 @@ func get_metrics(params: Dictionary) -> Dictionary:
 		total_usec += one
 		slowest_usec = maxi(slowest_usec, one)
 	# Null rather than zero before a frame has been timed: no frame took no time.
+	var steps: int = 0
+	for one: int in _frame_physics:
+		steps += one
 	var frame_time: Variant = null
 	var frame_time_max: Variant = null
+	var physics_steps_per_second: Variant = null
 	if timed > 0:
 		frame_time = float(total_usec) / timed / 1000000.0
 		frame_time_max = slowest_usec / 1000000.0
+		if total_usec > 0:
+			physics_steps_per_second = steps * 1000000.0 / total_usec
 	var all: Dictionary = {
 		"fps": Engine.get_frames_per_second(),
 		"frame_time": frame_time,
 		"frame_time_max": frame_time_max,
 		"frames_timed": timed,
+		"physics_steps_per_second": physics_steps_per_second,
+		"physics_ticks_per_second": Engine.physics_ticks_per_second,
+		"max_physics_steps_per_frame": Engine.max_physics_steps_per_frame,
+		"time_scale": Engine.time_scale,
 		"process_time_max": Performance.get_monitor(Performance.TIME_PROCESS),
 		"physics_time": Performance.get_monitor(Performance.TIME_PHYSICS_PROCESS),
 		"vsync": _vsync(),

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)
@@ -98,6 +167,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 +226,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():