gdharness 1.3.69 → 1.3.71

package/build/cli.js

@@ -20498,7 +20498,7 @@ var init_tool_definitions = __esm(() => {
   };
   PROPERTIES = {
     type: "object",
-    description: `Properties to set, keyed by Godot property name. Vectors, colours and the like may be written as {"x": 1, "y": 2} or tagged {"_type": "Vector2", "x": 1, "y": 2}, which is the form a read answers with, so a value read off one node can be written straight to another. One carrying a field its type has not, such as a z for a Vector2, is refused naming it. A colour may also be given as its html code, "#ff8000" or "#ff800080". A key may also be a colon path into one of the components of a vector, a colour, a rectangle or a transform, as GDScript names them, so one axis is written alone: "position:x", "modulate:a", "region_rect:size:y". A component the value does not have is refused, naming the ones it has. A property holding a node takes the path to it from the node being set, such as "../Player". A property holding a Resource takes the res:// path of a file, which a read answers with its class and, when its script declares one, scriptClass, or a resource built into the scene as {"_type": "CircleShape2D", "radius": 8}, its class (an engine class or a script's class_name) beside its properties. A typed list or map of resources or nodes, such as Array[Item], takes each in the same forms, a node by its path. A read answers a resource built into the scene in that form, with what it holds away from the defaults, so it too can be written to another node. script takes the res:// path of a script to attach, one with no class_name included, and is attached before the rest are set, so the properties it declares can be given beside it. Each value is read back once set, and one the engine changed or refused is refused with what it holds. An enum property takes its number or the name of a value: as the script spells it, as the inspector shows it, or for an engine enum as its constant, so Add or BLEND_MODE_ADD, and Bottom or VERTICAL_ALIGNMENT_BOTTOM for a global one. A value past an export range, or a number no value of an enum has, is written as given and named under outsideDeclared. A key may reach into a resource built into this one: the property holding it, a slash, then one of its own, so a TileSet's first atlas source takes "sources/0/0:0/0/probability". A list of such resources is stepped into by an element's index, so "lines/1/text" is the text of the second resource in lines and the others are left as they were. A resource kept in a file of its own, or built into the scene an instance comes from, is written in that file, or replaced here by one of this file's own. The next element of a list is made by writing to it, as the inspector's Add Element makes it: physics_layer_0/collision_layer on a TileSet with no physics layer makes its first, and "sources/0/0:0/0/physics_layer_0/polygon_0/points" a tile's first collision polygon on that layer. ${WHOLE_NUMBERS}`,
+    description: `Properties to set, keyed by Godot property name. Vectors, colours and the like may be written as {"x": 1, "y": 2} or tagged {"_type": "Vector2", "x": 1, "y": 2}, which is the form a read answers with, so a value read off one node can be written straight to another. One carrying a field its type has not, such as a z for a Vector2, is refused naming it. A colour may also be given as its html code, "#ff8000" or "#ff800080". A key may also be a colon path into one of the components of a vector, a colour, a rectangle or a transform, as GDScript names them, so one axis is written alone: "position:x", "modulate:a", "region_rect:size:y". A component the value does not have is refused, naming the ones it has. A property holding a node takes the path to it from the node being set, such as "../Player". A property holding a Resource takes the res:// path of a file, which a read answers with its class and, when its script declares one, scriptClass, or a resource built into the scene as {"_type": "CircleShape2D", "radius": 8}, its class (an engine class or a script's class_name) beside its properties. A typed list or map of resources or nodes, such as Array[Item], takes each in the same forms, a node by its path. A read answers a resource built into the scene in that form, with what it holds away from the defaults, so it too can be written to another node. script takes the res:// path of a script to attach, one with no class_name included, and is attached before the rest are set, so the properties it declares can be given beside it. Each value is read back once set, and one the engine changed or refused is refused with what it holds. An enum property takes its number or the name of a value: as the script spells it, as the inspector shows it, or for an engine enum as its constant, so Add or BLEND_MODE_ADD, and Bottom or VERTICAL_ALIGNMENT_BOTTOM for a global one. A value past an export range, or a number no value of an enum has, is written as given and named under outsideDeclared. A key may reach into a resource built into this one: the property holding it, a slash, then one of its own, so a TileSet's first atlas source takes "sources/0/0:0/0/probability". A list of such resources is stepped into by an element's index, so "lines/1/text" is the text of the second resource in lines and the others are left as they were. A resource kept in a file of its own, or built into the scene an instance comes from, is written in that file, or replaced here by one of this file's own. The next element of a list is made by writing to it, as the inspector's Add Element makes it: physics_layer_0/collision_layer on a TileSet with no physics layer makes its first, and "sources/0/0:0/0/physics_layer_0/polygon_0/points" a tile's first collision polygon on that layer. null for a "metadata/" key takes that entry off, as the inspector's delete button does, and the answer names it under metadataRemoved. ${WHOLE_NUMBERS}`,
     additionalProperties: true
   };
   XY = {
@@ -21259,7 +21259,7 @@ var init_tool_definitions = __esm(() => {
         placeholder: {
           type: "boolean",
           ops: ["add", "set"],
-          description: "add, with instancePath, or set, on an instance this scene places: whether it is saved as the editor's Load as Placeholder saves it, as `instance_placeholder` in the file. A game then gets an InstancePlaceholder there and loads the scene itself, while the editor still shows it. The answer says placeholder as the file now holds it."
+          description: "add, with instancePath, or set, on an instance this scene places: whether it is saved as the editor's Load as Placeholder saves it, as `instance_placeholder` in the file. A game then gets an InstancePlaceholder there and loads the scene itself, while the editor still shows it. A placeholder loads without its children, so it never has editableChildren too. Passing editableChildren false with placeholder true drops the children's saved values. The answer says placeholder as the file now holds it."
         },
         addGroups: {
           type: "array",

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

@@ -69,6 +69,9 @@ var _outside_declared: Dictionary = {}
 # The node paths the last write_all wrote that name no node from the node written, by property, as
 # a sentence saying so.
 var _names_no_node: Dictionary = {}
+## The metadata entries the last write_all took off, by the property names given. Godot reads a null
+## set on a metadata entry as its removal, as the inspector's delete button does.
+var metadata_removed: Array[String] = []
 
 
 ## Turns what arrived over the wire into the Godot value a property wants.
@@ -204,6 +207,7 @@ func write_all(target: Object, properties: Dictionary) -> String:
 	_names_no_node = {}
 	moved_by_engine = {}
 	unheld = ""
+	metadata_removed = []
 	var named: Dictionary = {}
 	for key: Variant in properties:
 		named[str(key).get_slice(":", 0)] = true
@@ -238,6 +242,15 @@ func write_all(target: Object, properties: Dictionary) -> String:
 		var place: Array = GdhPropertyPaths.holder_of(target, property, home)
 		var holder: Object = place[0]
 		var name: String = place[1]
+		var entry: String = name.trim_prefix("metadata/")
+		if (
+			properties[key] == null
+			and name.begins_with("metadata/")
+			and holder.has_meta(entry)
+		):
+			holder.remove_meta(entry)
+			metadata_removed.append(property)
+			continue
 		var declared: Dictionary = declaration(holder, name)
 		if declared.is_empty():
 			var elsewhere: String = GdhPropertyPaths.held_elsewhere(holder, name, home)
@@ -329,7 +342,7 @@ func write_all(target: Object, properties: Dictionary) -> String:
 			)
 	for property: String in before:
 		var now: Variant = target.get(property)
-		if not GdhSame.same(now, before[property]):
+		if not metadata_removed.has(property) and not GdhSame.same(now, before[property]):
 			_also_changed[property] = [before[property], now]
 	if target is Node:
 		_names_no_node = GdhDeclared.naming_nothing(target as Node, given)
@@ -384,6 +397,8 @@ func _laid_out(control: Control, name: String) -> String:
 ## as a scene answer names one. Called before the scene is written, since the write frees the nodes
 ## these values can hold.
 func note_write(answer: Dictionary, relative_to: Node = null) -> void:
+	if not metadata_removed.is_empty():
+		answer["metadataRemoved"] = metadata_removed.duplicate()
 	if not _outside_declared.is_empty():
 		answer["outsideDeclared"] = _outside_declared.duplicate()
 	if not _names_no_node.is_empty():

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

@@ -79,6 +79,10 @@ var _copied_from: Dictionary = {}
 var _reached: Dictionary = {}
 ## The file as it was opened, to compare its embedded resources with what the write saves.
 var _text: String = ""
+## The unique_id each placeholder put back as its instance had in the file, by the instance's object
+## id. Scripts cannot set one, the engine gives the instance a new one as it packs it, and a scene
+## inheriting this one finds a moved node by it.
+var _held_ids: Dictionary = {}
 ## The engine properties a put back did not take on a node, as "id:name": the engine derives them
 ## from where the node is, as it keeps layout_mode at Container under a container, and stores the
 ## same from an editor.
@@ -155,6 +159,8 @@ func open(scene_path: String, for_writing: bool) -> Dictionary:
 func _unhold_placeholders() -> void:
 	var held: Array[InstancePlaceholder] = []
 	_placeholders_under(root, held)
+	var as_text: bool = path.ends_with(".tscn") and not held.is_empty()
+	var text: String = FileAccess.get_file_as_string(path) if as_text else ""
 	for one: InstancePlaceholder in held:
 		var packed: PackedScene = (
 			ResourceLoader.load(one.get_instance_path(), "PackedScene") as PackedScene
@@ -168,15 +174,78 @@ func _unhold_placeholders() -> void:
 		var values: Dictionary = one.get_stored_values()
 		for key: Variant in values:
 			instance.set(str(key), values[key])
+		var filed_id: String = _filed_id(text, _header_of(root.get_path_to(one)))
 		# replace_by moves the place and the groups.
 		one.replace_by(instance, true)
 		instance.owner = root
 		instance.scene_file_path = one.get_instance_path()
 		instance.set_scene_instance_load_placeholder(true)
+		if not filed_id.is_empty():
+			_held_ids[instance.get_instance_id()] = filed_id
 		_repointed(root, one, instance)
 		one.free()
 
 
+## How a text scene opens the entry of the node at [param at], a path from the root.
+static func _header_of(at: NodePath) -> String:
+	var named: String = str(at.get_name(at.get_name_count() - 1))
+	var parent: String = "." if at.get_name_count() == 1 else str(at).get_base_dir()
+	return '[node name="%s" parent="%s"' % [named.c_escape(), parent.c_escape()]
+
+
+## The unique_id [param text] gives the node whose entry opens with [param header], or "".
+static func _filed_id(text: String, header: String) -> String:
+	var id: RegEx = RegEx.create_from_string(" unique_id=(\\d+)")
+	for line: String in text.split("\n"):
+		if line.begins_with(header + " ") or line.begins_with(header + "]"):
+			var found: RegExMatch = id.search(line)
+			return "" if found == null else found.get_string(1)
+	return ""
+
+
+## The unique_id to write back on each placeholder put back as its instance, by its entry's header,
+## for those still in the scene.
+func _ids_to_keep() -> Dictionary:
+	var keep: Dictionary = {}
+	for key: Variant in _held_ids:
+		var node: Node = instance_from_id(GdhRead.as_int(key)) as Node
+		if node != null and root.is_ancestor_of(node):
+			keep[_header_of(root.get_path_to(node))] = _held_ids[key]
+	return keep
+
+
+## Saves [param packed] at [param file_path] as [method save_packed] does, with the unique_ids in
+## [param keep].
+static func _saved_keeping_ids(packed: PackedScene, file_path: String, keep: Dictionary) -> Error:
+	var saving: Error = GdhSceneUids.save_keeping_uid(packed, file_path)
+	return saving if saving != OK else _keep_ids(file_path, keep)
+
+
+## Writes back on the text scene at [param file_path] the unique_id of each entry in [param keep],
+## by its header.
+static func _keep_ids(file_path: String, keep: Dictionary) -> Error:
+	if keep.is_empty():
+		return OK
+	var lines: PackedStringArray = FileAccess.get_file_as_string(file_path).split("\n")
+	var id: RegEx = RegEx.create_from_string(" unique_id=\\d+")
+	var changed: bool = false
+	for index: int in lines.size():
+		for header: Variant in keep:
+			var opening: String = str(header)
+			if lines[index].begins_with(opening + " ") or lines[index].begins_with(opening + "]"):
+				lines[index] = id.sub(lines[index], " unique_id=" + str(keep[header]))
+				changed = true
+	if not changed:
+		return OK
+	var file: FileAccess = FileAccess.open(file_path, FileAccess.WRITE)
+	if file == null:
+		return FileAccess.get_open_error()
+	if not file.store_string("\n".join(lines)):
+		return ERR_FILE_CANT_WRITE
+	file.close()
+	return OK
+
+
 ## Every InstancePlaceholder below [param top] that this scene places, into [param into].
 func _placeholders_under(top: Node, into: Array[InstancePlaceholder]) -> void:
 	for child: Node in top.get_children():
@@ -1077,6 +1146,7 @@ func _write(check: Callable) -> Dictionary:
 		if not missing.is_empty():
 			return refuse("Nothing was written: " + missing)
 	var also: Array[Dictionary] = _also_saved(packed.get_state())
+	var keep: Dictionary = _ids_to_keep() if headless and path.ends_with(".tscn") else {}
 	close()
 	var previous: Variant = null
 	if FileAccess.file_exists(path):
@@ -1088,12 +1158,18 @@ func _write(check: Callable) -> Dictionary:
 		values.append_array(_stored_at(state, index).values())
 	var carried: Dictionary = GdhHeadlessCheck.embedded_in(values, {})
 	var written: Dictionary = save_packed(packed, path)
+	if written.is_empty():
+		var ids_kept: Error = _keep_ids(path, keep)
+		if ids_kept != OK:
+			written = {
+				"ok": false, "error": "Failed to save %s: %s" % [path, error_string(ids_kept)],
+			}
 	if not written.is_empty() or not headless or not path.ends_with(".tscn"):
 		if written.is_empty():
 			also_saved.append_array(also)
 		return written
 	var just_saved: GdhHeadlessCheck.GdhSaved = GdhHeadlessCheck.GdhSaved.new(
-		path, _text, func() -> Error: return GdhSceneUids.save_keeping_uid(packed, path)
+		path, _text, func() -> Error: return _saved_keeping_ids(packed, path, keep)
 	)
 	var unkept: String = GdhHeadlessCheck.settle_saved(
 		just_saved,

package/build/godot/addons/gdharness_editor/tools/resource_tools.gd

@@ -338,7 +338,10 @@ func modify_resource(args: Dictionary) -> Dictionary:
 	)
 	if not also.is_empty():
 		answer["alsoSaved"] = also
-	answer["properties"] = _held(resource, properties.keys())
+	var kept: Array = properties.keys().filter(
+		func(key: Variant) -> bool: return not _properties.metadata_removed.has(str(key))
+	)
+	answer["properties"] = _held(resource, kept)
 	return answer
 
 

package/build/godot/addons/gdharness_editor/tools/scene_tools.gd

@@ -1181,6 +1181,39 @@ func set_node_properties(args: Dictionary) -> Dictionary:
 	if not foreign.is_empty():
 		return scene.refuse(foreign)
 
+	# A placeholder loads without its children, so the editor never keeps both settings on.
+	var wants_placeholder: bool = placeholder != null and GdhRead.as_bool(placeholder)
+	var wants_editable: bool = editable != null and GdhRead.as_bool(editable)
+	if wants_placeholder and wants_editable:
+		return scene.refuse(
+			(
+				"placeholder and editableChildren cannot both be true, "
+				+ "since a placeholder loads without its children."
+			)
+		)
+	# The engine asks the root whether it is an editable instance of itself only with an error.
+	var children_open: bool = node != scene.root and scene.root.is_editable_instance(node)
+	if wants_placeholder and editable == null and children_open:
+		return scene.refuse(
+			(
+				(
+					"%s has editable children, which a placeholder cannot keep. Pass "
+					+ "editableChildren false with placeholder true to drop their saved values."
+				)
+				% scene.path_of(node)
+			)
+		)
+	if wants_editable and placeholder == null and node.get_scene_instance_load_placeholder():
+		return scene.refuse(
+			(
+				(
+					"%s is a placeholder, which loads without its children. "
+					+ "Pass placeholder false with editableChildren true."
+				)
+				% scene.path_of(node)
+			)
+		)
+
 	var dropped: Dictionary = {}
 	if editable != null:
 		var not_an_instance: String = GdhKin.set_editable(scene, node, GdhRead.as_bool(editable))
@@ -1214,8 +1247,10 @@ func set_node_properties(args: Dictionary) -> Dictionary:
 		return scene.refuse(ungrouped)
 
 	var held: Dictionary = {}
+	var removed: Array[String] = _properties.metadata_removed.duplicate()
 	for key: Variant in properties:
-		held[str(key)] = _readable(node, _properties.read_at(node, str(key)))
+		if not removed.has(str(key)):
+			held[str(key)] = _readable(node, _properties.read_at(node, str(key)))
 	var new_path: String = scene.path_of(node)
 	var answer: Dictionary = { "ok": true, "nodePath": new_path, "properties": held }
 	_properties.note_write(answer, node)

package/build/godot/operations/property_values.gd

@@ -69,6 +69,9 @@ var _outside_declared: Dictionary = {}
 # The node paths the last write_all wrote that name no node from the node written, by property, as
 # a sentence saying so.
 var _names_no_node: Dictionary = {}
+## The metadata entries the last write_all took off, by the property names given. Godot reads a null
+## set on a metadata entry as its removal, as the inspector's delete button does.
+var metadata_removed: Array[String] = []
 
 
 ## Turns what arrived over the wire into the Godot value a property wants.
@@ -204,6 +207,7 @@ func write_all(target: Object, properties: Dictionary) -> String:
 	_names_no_node = {}
 	moved_by_engine = {}
 	unheld = ""
+	metadata_removed = []
 	var named: Dictionary = {}
 	for key: Variant in properties:
 		named[str(key).get_slice(":", 0)] = true
@@ -238,6 +242,15 @@ func write_all(target: Object, properties: Dictionary) -> String:
 		var place: Array = GdhPropertyPaths.holder_of(target, property, home)
 		var holder: Object = place[0]
 		var name: String = place[1]
+		var entry: String = name.trim_prefix("metadata/")
+		if (
+			properties[key] == null
+			and name.begins_with("metadata/")
+			and holder.has_meta(entry)
+		):
+			holder.remove_meta(entry)
+			metadata_removed.append(property)
+			continue
 		var declared: Dictionary = declaration(holder, name)
 		if declared.is_empty():
 			var elsewhere: String = GdhPropertyPaths.held_elsewhere(holder, name, home)
@@ -329,7 +342,7 @@ func write_all(target: Object, properties: Dictionary) -> String:
 			)
 	for property: String in before:
 		var now: Variant = target.get(property)
-		if not GdhSame.same(now, before[property]):
+		if not metadata_removed.has(property) and not GdhSame.same(now, before[property]):
 			_also_changed[property] = [before[property], now]
 	if target is Node:
 		_names_no_node = GdhDeclared.naming_nothing(target as Node, given)
@@ -384,6 +397,8 @@ func _laid_out(control: Control, name: String) -> String:
 ## as a scene answer names one. Called before the scene is written, since the write frees the nodes
 ## these values can hold.
 func note_write(answer: Dictionary, relative_to: Node = null) -> void:
+	if not metadata_removed.is_empty():
+		answer["metadataRemoved"] = metadata_removed.duplicate()
 	if not _outside_declared.is_empty():
 		answer["outsideDeclared"] = _outside_declared.duplicate()
 	if not _names_no_node.is_empty():

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdharness",
-  "version": "1.3.69",
+  "version": "1.3.71",
   "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",