gdharness 1.3.9 → 1.3.11

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) + "."

package/build/godot/addons/gdharness_editor/file_reads.gd

@@ -16,15 +16,19 @@ const GdhSerialisation = preload("serialisation.gd")
 
 
 ## The nodes of [param scene_path] as {name, type, path, children}, with instanceOf and
-## editableChildren on a node that instances another scene and every stored property when
-## [param include_properties] is set, the file's value or the default where it sets none.
+## editableChildren on a node that instances another scene and its stored properties when
+## [param include_properties] is set, the file's value or the default where it sets none, and on a
+## node another file makes setHere, the properties this file sets on it. Defaults the file leaves
+## alone are counted as defaultsLeftOut rather than listed unless [param include_defaults] is set.
 ## [param depth] -1 reads every level.
-static func scene_tree(scene_path: String, depth: int, include_properties: bool) -> Dictionary:
+static func scene_tree(
+	scene_path: String, depth: int, include_properties: bool, include_defaults: bool
+) -> Dictionary:
 	var laid: Dictionary = _laid(scene_path)
 	if not laid.get("ok", false):
 		return laid
 	var nodes: Dictionary = laid["nodes"]
-	return {"ok": true, "tree": _entry(nodes, ".", include_properties, depth, 0)}
+	return {"ok": true, "tree": _entry(nodes, ".", include_properties, include_defaults, depth, 0)}
 
 
 ## The node at [param node_path] in [param scene_path] as {ok, name, type, properties}, laid as
@@ -176,6 +180,7 @@ static func _lay(
 				continue
 			else:
 				nodes[path] = _made(str(state.get_node_type(index)))
+				nodes[path]["madeHere"] = loaded != null
 			if ids[index] >= 0:
 				nodes[path]["uniqueId"] = ids[index]
 			# Laid at the root with no scene handed in is a scene the one being read inherits, and the
@@ -202,10 +207,15 @@ static func _lay(
 			if not grouped.has(str(group)):
 				grouped.append(str(group))
 		var held: Dictionary = nodes[path]["properties"]
+		# What the file being read sets, kept apart for a node another file makes, whose values read
+		# the same whether this scene changed them or that one gave them.
+		var laid: Dictionary = nodes[path]
+		var set_here: Array = laid.get_or_add("setHere", [])
 		for property: int in state.get_node_property_count(index):
-			held[str(state.get_node_property_name(index, property))] = state.get_node_property_value(
-				index, property
-			)
+			var named: String = str(state.get_node_property_name(index, property))
+			held[named] = state.get_node_property_value(index, property)
+			if loaded != null and not set_here.has(named):
+				set_here.append(named)
 	# Only the scene being read and the scenes it inherits share its root, the owner whose editable
 	# instances a write here sets; a file instanced below makes its own owner's editable.
 	if prefix == ".":
@@ -321,7 +331,12 @@ static func _joined(prefix: String, given: String) -> String:
 
 
 static func _entry(
-	nodes: Dictionary, path: String, include_properties: bool, depth: int, current_depth: int
+	nodes: Dictionary,
+	path: String,
+	include_properties: bool,
+	include_defaults: bool,
+	depth: int,
+	current_depth: int
 ) -> Dictionary:
 	var node: Dictionary = nodes[path]
 	var children: Array[Dictionary] = []
@@ -344,7 +359,21 @@ static func _entry(
 		data["groups"] = sorted
 	if include_properties:
 		var given: Dictionary = node["properties"]
-		data["properties"] = _stored(str(node["type"]), given)
+		var stored: Dictionary = _stored(str(node["type"]), given, include_defaults)
+		data["properties"] = stored["properties"]
+		if stored["left_out"] > 0:
+			data["defaultsLeftOut"] = stored["left_out"]
+		var cells: int = _cell_count(str(node["type"]), given)
+		if cells >= 0:
+			data["cellCount"] = cells
+			data["cellsListedBy"] = (
+				"scene_node get with nodePath %s, which lists them as set_tilemap_cells takes them" % path
+			)
+		if not node.get("madeHere", false):
+			var kept: Array = node.get("setHere", [])
+			var set_here: Array = kept.duplicate()
+			set_here.sort()
+			data["setHere"] = set_here
 	var below: Array[String] = node["children"]
 	# Counted rather than left as an empty list, which reads as a node with no children.
 	if depth >= 0 and current_depth >= depth:
@@ -352,19 +381,56 @@ static func _entry(
 			data["childrenNotListed"] = below.size()
 		return data
 	for child: String in below:
-		children.append(_entry(nodes, child, include_properties, depth, current_depth + 1))
+		children.append(_entry(nodes, child, include_properties, include_defaults, depth, current_depth + 1))
 	return data
 
 
+## How many cells a TileMapLayer or TileMap of [param type] holds under the values [param given], or
+## -1 when it is another node or the file sets none of its cells. The file keeps them as packed bytes,
+## which a read of the tree answered with alone, so a caller decoded the base64 to learn what was
+## painted. Only cells the file sets are counted: an instance's come from its own scene.
+static func _cell_count(type: String, given: Dictionary) -> int:
+	if not ClassDB.class_exists(type) or not ClassDB.can_instantiate(type):
+		return -1
+	var single: bool = ClassDB.is_parent_class(type, "TileMapLayer")
+	if not single and not ClassDB.is_parent_class(type, "TileMap"):
+		return -1
+	var painted: bool = false
+	for property: Variant in given:
+		var named: String = str(property)
+		if named == "tile_map_data" or (named.begins_with("layer_") and named.ends_with("/tile_data")):
+			painted = true
+	if not painted:
+		return -1
+	var bare: Node = ClassDB.instantiate(type)
+	for property: Variant in given:
+		if property != "script":
+			bare.set(str(property), given[property])
+	var count: int = 0
+	if single:
+		count = (bare as TileMapLayer).get_used_cells().size()
+	else:
+		var layered: TileMap = bare as TileMap
+		for layer: int in layered.get_layers_count():
+			count += layered.get_used_cells(layer).size()
+	bare.free()
+	return count
+
+
 ## Every property a node of [param type] stores, with the value [param given] sets or the default,
-## read as a node holding those values would answer them.
+## read as a node holding those values would answer them, as {properties, left_out}.
 ##
 ## The engine's half is read off a bare node of the class with the file's values set on it, which
 ## runs no script: what a node lists depends on its values (a thread group's settings appear only
 ## once it has one) and some setters set others (a Control's anchors preset sets how it grows), so
 ## the class's defaults and the file's entries alone answered neither. The script's half is its
 ## declared defaults under the file's values.
-static func _stored(type: String, given: Dictionary) -> Dictionary:
+##
+## Without [param include_defaults], properties keeps only what the file sets and what differs from
+## a node of the class holding none of its values, and left_out counts the rest. Every Control
+## carries a hundred properties, and ten of them came to 57 KB of defaults around the few values a
+## menu scene set.
+static func _stored(type: String, given: Dictionary, include_defaults: bool) -> Dictionary:
 	var attached: Variant = given.get("script")
 	var script: Script = attached if attached is Script else null
 	var scripted: Dictionary = {}
@@ -374,8 +440,10 @@ static func _stored(type: String, given: Dictionary) -> Dictionary:
 			if not property.is_empty() and GdhRead.as_int(declared.get("usage", 0)) & PROPERTY_USAGE_STORAGE:
 				scripted[property] = script.get_property_default_value(property)
 	var values: Dictionary = {}
+	var defaults: Dictionary = {}
 	if ClassDB.class_exists(type) and ClassDB.can_instantiate(type):
 		var bare: Object = ClassDB.instantiate(type)
+		var plain: Object = ClassDB.instantiate(type)
 		for property: Variant in given:
 			if property != "script" and not scripted.has(property):
 				bare.set(str(property), given[property])
@@ -383,18 +451,30 @@ static func _stored(type: String, given: Dictionary) -> Dictionary:
 			var property: String = str(declared.get("name", ""))
 			if not property.is_empty() and GdhRead.as_int(declared.get("usage", 0)) & PROPERTY_USAGE_STORAGE:
 				values[property] = bare.get(property)
-		if bare is Node:
-			bare.free()
+				defaults[property] = plain.get(property)
+		for made: Object in [bare, plain]:
+			if made is Node:
+				made.free()
 	for property: String in scripted:
 		values[property] = scripted[property]
+		defaults[property] = scripted[property]
 	# Given last, which keeps what a bare node cannot hold: the script itself, and a path to a node
 	# for a property that holds the node once it is in a tree.
 	values.merge(given, true)
 	var serialiser: GdhSerialisation = GdhSerialisation.new()
 	var answered: Dictionary = {}
+	var left_out: int = 0
 	for property: Variant in values:
+		var as_default: bool = (
+			not given.has(property)
+			and defaults.has(property)
+			and GdhSame.same(values[property], defaults[property])
+		)
+		if as_default and not include_defaults:
+			left_out += 1
+			continue
 		answered[property] = serialiser.serialize_value(values[property])
-	return answered
+	return {"properties": answered, "left_out": left_out}
 
 
 ## What a resource file holds, in the form modify takes, so a value read here can be written back.
@@ -407,12 +487,16 @@ static func resource(res_path: String, include_defaults: bool) -> Dictionary:
 	var file: String = res_path.get_slice("::", 0)
 	if not FileAccess.file_exists(file):
 		return {"ok": false, "error": "No resource at " + file}
-	var loaded: Resource = ResourceLoader.load(file, "", ResourceLoader.CACHE_MODE_IGNORE)
-	if loaded == null:
+	var whole: Resource = ResourceLoader.load(file, "", ResourceLoader.CACHE_MODE_IGNORE)
+	if whole == null:
 		return {"ok": false, "error": "%s did not load as a resource." % file}
+	# The file's resource is held until the read is done, since what it keeps can depend on it: a
+	# TileSet that goes unlinks its sources, and an atlas source with no TileSet lists none of its
+	# tiles' physics, navigation or custom data.
+	var loaded: Resource = whole
 	if file != res_path:
 		var id: String = res_path.trim_prefix(file + "::")
-		var inner: Resource = _kept_in(loaded, file, id, {})
+		var inner: Resource = _kept_in(whole, file, id, {})
 		if inner == null:
 			return {"ok": false, "error": "%s keeps no resource with the id %s." % [file, id]}
 		loaded = inner