godot-mcp-runtime 2.3.0 → 3.1.0

package/dist/scripts/godot_operations.gd

@@ -10,11 +10,15 @@ func _init():
 	# Check for debug flag
 	debug_mode = "--debug-godot" in args
 
+	# SceneTree.quit(n) only schedules a quit for end-of-frame in Godot 4.
+	# Every quit(1) must be followed by `return` to halt the failing path,
+	# otherwise control falls through into success-print + scene save.
 	# Find the script argument and determine the positions of operation and params
 	var script_index = args.find("--script")
 	if script_index == -1:
 		log_error("Could not find --script argument")
 		quit(1)
+		return
 
 	var operation_index = script_index + 2
 	var params_index = script_index + 3
@@ -23,6 +27,7 @@ func _init():
 		log_error("Usage: godot --headless --script godot_operations.gd <operation> <json_params>")
 		log_error("Not enough command-line arguments provided.")
 		quit(1)
+		return
 
 	log_debug("All arguments: " + str(args))
 
@@ -42,10 +47,12 @@ func _init():
 		log_error("Failed to parse JSON parameters: " + params_json)
 		log_error("JSON Error: " + json.get_error_message() + " at line " + str(json.get_error_line()))
 		quit(1)
+		return
 
 	if not params:
 		log_error("Failed to parse JSON parameters: " + params_json)
 		quit(1)
+		return
 
 	log_info("Executing operation: " + operation)
 
@@ -61,19 +68,13 @@ func _init():
 			export_mesh_library(params)
 		"save_scene":
 			save_scene(params)
-		"get_uid":
-			get_uid(params)
-		"resave_resources":
-			resave_resources(params)
-		# New node operations
-		"delete_node":
-			delete_node(params)
-		"set_node_property":
-			set_node_property(params)
+		# Node operations (always-array)
+		"delete_nodes":
+			delete_nodes(params)
+		"set_node_properties":
+			set_node_properties(params)
 		"get_node_properties":
 			get_node_properties(params)
-		"list_nodes":
-			list_nodes(params)
 		"get_scene_tree":
 			get_scene_tree(params)
 		"attach_script":
@@ -93,15 +94,13 @@ func _init():
 			validate_batch(params)
 		"batch_scene_operations":
 			batch_scene_operations(params)
-		"batch_set_node_properties":
-			batch_set_node_properties(params)
-		"batch_get_node_properties":
-			batch_get_node_properties(params)
 		_:
 			log_error("Unknown operation: " + operation)
 			quit(1)
+			return
 
 	quit()
+	return
 
 # Logging functions
 func log_debug(message):
@@ -220,14 +219,22 @@ func load_scene_instance(scene_path: String):
 
 	return instance
 
-# Helper to find a node by path
+# Helper to find a node by path. Accepts "root", ".", "" (all → scene_root),
+# the actual scene root's name (e.g. "Main"), or a path with either as the first
+# segment (e.g. "root/Button" or "Main/Button"). Bare paths ("Button") resolve
+# normally via get_node_or_null.
 func find_node_by_path(scene_root: Node, node_path: String) -> Node:
-	if node_path == "root" or node_path.is_empty():
+	if node_path == "" or node_path == "." or node_path == "root":
+		return scene_root
+	if node_path == String(scene_root.name):
 		return scene_root
 
 	var path = node_path
-	if path.begins_with("root/"):
-		path = path.substr(5)
+	var first_slash = path.find("/")
+	if first_slash != -1:
+		var first_segment = path.substr(0, first_slash)
+		if first_segment == "root" or first_segment == String(scene_root.name):
+			path = path.substr(first_slash + 1)
 
 	if path.is_empty():
 		return scene_root
@@ -252,6 +259,20 @@ func save_scene_to_path(scene_root: Node, save_path: String) -> bool:
 
 	return true
 
+# Ensure the parent directory of a res:// path exists, creating it recursively
+# if needed. Returns true on success or when the directory already exists.
+func _ensure_res_dir(full_res_path: String) -> bool:
+	var dir_path = full_res_path.get_base_dir()
+	if dir_path == "res://" or dir_path.is_empty():
+		return true
+	var dir = DirAccess.open("res://")
+	if not dir:
+		return false
+	var relative_dir = dir_path.substr(6) if dir_path.begins_with("res://") else dir_path
+	if relative_dir.is_empty() or dir.dir_exists(relative_dir):
+		return true
+	return dir.make_dir_recursive(relative_dir) == OK
+
 # Create a new scene with a specified root node type
 func create_scene(params):
 	printerr("Creating scene: " + params.scene_path)
@@ -268,66 +289,94 @@ func create_scene(params):
 	if not scene_root:
 		log_error("Failed to instantiate node of type: " + root_node_type)
 		quit(1)
+		return
 
 	scene_root.name = "root"
 	scene_root.owner = scene_root
 
-	# Ensure directory exists
-	var scene_dir = full_scene_path.get_base_dir()
-	if scene_dir != "res://" and not scene_dir.is_empty():
-		var dir = DirAccess.open("res://")
-		if dir:
-			var relative_dir = scene_dir.substr(6) if scene_dir.begins_with("res://") else scene_dir
-			if not relative_dir.is_empty() and not dir.dir_exists(relative_dir):
-				var make_error = dir.make_dir_recursive(relative_dir)
-				if make_error != OK:
-					log_error("Failed to create directory: " + relative_dir)
-					quit(1)
+	if not _ensure_res_dir(full_scene_path):
+		log_error("Failed to create directory for scene: " + full_scene_path)
+		quit(1)
+		return
 
 	if save_scene_to_path(scene_root, full_scene_path):
 		print("Scene created successfully at: " + params.scene_path)
 	else:
 		log_error("Failed to create scene: " + params.scene_path)
 		quit(1)
+		return
 
 # Add a node to an existing scene
+# Apply an add_node mutation without saving. Shared by standalone add_node
+# and batch_scene_operations so both paths validate identically.
+# Returns {"ok": bool, "error": String}; error is empty on success.
+func _apply_add_node(scene_root: Node, op: Dictionary) -> Dictionary:
+	var parent_path = "root"
+	if op.has("parent_node_path"):
+		parent_path = op.parent_node_path
+	var parent = find_node_by_path(scene_root, parent_path)
+	if not parent:
+		return {"ok": false, "error": "Parent node not found: " + parent_path}
+	if not op.has("node_type") or op.node_type == "":
+		return {"ok": false, "error": "node_type is required for add_node"}
+	if not op.has("node_name") or op.node_name == "":
+		return {"ok": false, "error": "node_name is required for add_node"}
+	var new_node = instantiate_class(op.node_type)
+	if not new_node:
+		return {"ok": false, "error": "Failed to instantiate node of type: " + op.node_type}
+	new_node.name = op.node_name
+	if op.has("properties"):
+		for property in op.properties:
+			new_node.set(property, _coerce_property_value(op.properties[property]))
+	parent.add_child(new_node)
+	new_node.owner = scene_root
+	return {"ok": true, "error": ""}
+
+# Apply a load_sprite mutation without saving. Shared by standalone load_sprite
+# and batch_scene_operations.
+func _apply_load_sprite(scene_root: Node, op: Dictionary) -> Dictionary:
+	if not op.has("node_path") or op.node_path == "":
+		return {"ok": false, "error": "node_path is required for load_sprite"}
+	if not op.has("texture_path") or op.texture_path == "":
+		return {"ok": false, "error": "texture_path is required for load_sprite"}
+	var sprite_node = find_node_by_path(scene_root, op.node_path)
+	if not sprite_node:
+		return {"ok": false, "error": "Node not found: " + op.node_path}
+	if not (sprite_node is Sprite2D or sprite_node is Sprite3D or sprite_node is TextureRect):
+		return {"ok": false, "error": "Node is not a sprite-compatible type: " + sprite_node.get_class()}
+	var full_texture_path = normalize_scene_path(op.texture_path)
+	var texture = load(full_texture_path)
+	if not texture:
+		return {"ok": false, "error": "Failed to load texture: " + full_texture_path}
+	if not (texture is Texture2D):
+		return {"ok": false, "error": "Loaded resource is not a Texture2D: " + full_texture_path}
+	# A texture without a resource_path is a runtime-only object — PackedScene.pack()
+	# cannot serialize it, so the assignment would silently vanish on save.
+	if texture.resource_path == "":
+		return {"ok": false, "error": "Texture has no resource_path — likely not imported. Open project in Godot editor once, or run 'godot --headless --editor --quit' to import assets."}
+	sprite_node.texture = texture
+	return {"ok": true, "error": ""}
+
 func add_node(params):
 	printerr("Adding node to scene: " + params.scene_path)
 
 	var scene_root = load_scene_instance(params.scene_path)
 	if not scene_root:
 		quit(1)
+		return
 
-	var parent_path = "root"
-	if params.has("parent_node_path"):
-		parent_path = params.parent_node_path
-
-	var parent = find_node_by_path(scene_root, parent_path)
-	if not parent:
-		log_error("Parent node not found: " + parent_path)
-		quit(1)
-
-	var new_node = instantiate_class(params.node_type)
-	if not new_node:
-		log_error("Failed to instantiate node of type: " + params.node_type)
+	var result = _apply_add_node(scene_root, params)
+	if not result.ok:
+		log_error(result.error)
 		quit(1)
-
-	new_node.name = params.node_name
-
-	if params.has("properties"):
-		var properties = params.properties
-		for property in properties:
-			log_debug("Setting property: " + property + " = " + str(properties[property]))
-			new_node.set(property, properties[property])
-
-	parent.add_child(new_node)
-	new_node.owner = scene_root
+		return
 
 	if save_scene_to_path(scene_root, params.scene_path):
 		print("Node '" + params.node_name + "' of type '" + params.node_type + "' added successfully")
 	else:
 		log_error("Failed to save scene after adding node")
 		quit(1)
+		return
 
 # Load a sprite into a Sprite2D node
 func load_sprite(params):
@@ -336,29 +385,20 @@ func load_sprite(params):
 	var scene_root = load_scene_instance(params.scene_path)
 	if not scene_root:
 		quit(1)
+		return
 
-	var sprite_node = find_node_by_path(scene_root, params.node_path)
-	if not sprite_node:
-		log_error("Node not found: " + params.node_path)
-		quit(1)
-
-	if not (sprite_node is Sprite2D or sprite_node is Sprite3D or sprite_node is TextureRect):
-		log_error("Node is not a sprite-compatible type: " + sprite_node.get_class())
-		quit(1)
-
-	var full_texture_path = normalize_scene_path(params.texture_path)
-	var texture = load(full_texture_path)
-	if not texture:
-		log_error("Failed to load texture: " + full_texture_path)
+	var result = _apply_load_sprite(scene_root, params)
+	if not result.ok:
+		log_error(result.error)
 		quit(1)
-
-	sprite_node.texture = texture
+		return
 
 	if save_scene_to_path(scene_root, params.scene_path):
 		print("Sprite loaded successfully with texture: " + params.texture_path)
 	else:
 		log_error("Failed to save scene after loading sprite")
 		quit(1)
+		return
 
 # Export a scene as a MeshLibrary resource
 func export_mesh_library(params):
@@ -367,6 +407,7 @@ func export_mesh_library(params):
 	var scene_root = load_scene_instance(params.scene_path)
 	if not scene_root:
 		quit(1)
+		return
 
 	var mesh_library = MeshLibrary.new()
 
@@ -398,22 +439,17 @@ func export_mesh_library(params):
 					mesh_library.set_item_shapes(item_id, [collision_child.shape])
 					break
 
-			if mesh_instance.mesh:
-				mesh_library.set_item_preview(item_id, mesh_instance.mesh)
+			mesh_library.set_item_preview(item_id, mesh_instance.mesh)
 
 			item_id += 1
 
 	if item_id > 0:
 		var full_output_path = normalize_scene_path(params.output_path)
 
-		# Ensure output directory exists
-		var output_dir = full_output_path.get_base_dir()
-		if output_dir != "res://":
-			var dir = DirAccess.open("res://")
-			if dir:
-				var relative_dir = output_dir.substr(6) if output_dir.begins_with("res://") else output_dir
-				if not relative_dir.is_empty() and not dir.dir_exists(relative_dir):
-					dir.make_dir_recursive(relative_dir)
+		if not _ensure_res_dir(full_output_path):
+			log_error("Failed to create directory for MeshLibrary: " + full_output_path)
+			quit(1)
+			return
 
 		var error = ResourceSaver.save(mesh_library, full_output_path)
 		if error == OK:
@@ -421,9 +457,11 @@ func export_mesh_library(params):
 		else:
 			log_error("Failed to save MeshLibrary: " + str(error))
 			quit(1)
+			return
 	else:
 		log_error("No valid meshes found in the scene")
 		quit(1)
+		return
 
 # Save changes to a scene file
 func save_scene(params):
@@ -432,6 +470,7 @@ func save_scene(params):
 	var scene_root = load_scene_instance(params.scene_path)
 	if not scene_root:
 		quit(1)
+		return
 
 	var save_path = params.new_path if params.has("new_path") else params.scene_path
 
@@ -440,217 +479,109 @@ func save_scene(params):
 	else:
 		log_error("Failed to save scene")
 		quit(1)
-
-# Find files with a specific extension recursively
-func find_files(path, extension):
-	var files = []
-	var dir = DirAccess.open(path)
-
-	if dir:
-		dir.list_dir_begin()
-		var file_name = dir.get_next()
-
-		while file_name != "":
-			if dir.current_is_dir() and not file_name.begins_with("."):
-				files.append_array(find_files(path + file_name + "/", extension))
-			elif file_name.ends_with(extension):
-				files.append(path + file_name)
-
-			file_name = dir.get_next()
-
-	return files
-
-# Get UID for a specific file
-func get_uid(params):
-	if not params.has("file_path"):
-		log_error("File path is required")
-		quit(1)
-
-	var file_path = normalize_scene_path(params.file_path)
-	printerr("Getting UID for file: " + file_path)
-
-	if not FileAccess.file_exists(file_path):
-		log_error("File does not exist: " + file_path)
-		quit(1)
-
-	var uid_path = file_path + ".uid"
-	var f = FileAccess.open(uid_path, FileAccess.READ)
-
-	if f:
-		var uid_content = f.get_as_text()
-		f.close()
-
-		var result = {
-			"file": file_path,
-			"uid": uid_content.strip_edges(),
-			"exists": true
-		}
-		print(JSON.stringify(result))
-	else:
-		var result = {
-			"file": file_path,
-			"exists": false,
-			"message": "UID file does not exist for this file. Use resave_resources to generate UIDs."
-		}
-		print(JSON.stringify(result))
-
-# Resave all resources to update UID references
-func resave_resources(params):
-	printerr("Resaving all resources to update UID references...")
-
-	var project_path = "res://"
-	if params.has("project_path"):
-		project_path = params.project_path
-		if not project_path.begins_with("res://"):
-			project_path = "res://" + project_path
-		if not project_path.ends_with("/"):
-			project_path += "/"
-
-	var scenes = find_files(project_path, ".tscn")
-	var success_count = 0
-	var error_count = 0
-
-	for scene_path in scenes:
-		var scene = load(scene_path)
-		if scene:
-			var error = ResourceSaver.save(scene, scene_path)
-			if error == OK:
-				success_count += 1
-			else:
-				error_count += 1
-				log_error("Failed to save: " + scene_path)
-		else:
-			error_count += 1
-			log_error("Failed to load: " + scene_path)
-
-	var scripts = find_files(project_path, ".gd") + find_files(project_path, ".shader") + find_files(project_path, ".gdshader")
-	var generated_uids = 0
-
-	for script_path in scripts:
-		var uid_path = script_path + ".uid"
-		var f = FileAccess.open(uid_path, FileAccess.READ)
-		if not f:
-			var res = load(script_path)
-			if res:
-				var error = ResourceSaver.save(res, script_path)
-				if error == OK:
-					generated_uids += 1
-
-	print("Resave operation complete. Scenes: " + str(success_count) + " saved, " + str(error_count) + " errors. UIDs generated: " + str(generated_uids))
+		return
 
 # ============================================
-# NEW NODE OPERATIONS
+# NODE OPERATIONS
 # ============================================
 
-# Delete a node from a scene
-func delete_node(params):
-	printerr("Deleting node from scene: " + params.scene_path)
-
-	var scene_root = load_scene_instance(params.scene_path)
-	if not scene_root:
-		quit(1)
-
-	var node = find_node_by_path(scene_root, params.node_path)
-	if not node:
-		log_error("Node not found: " + params.node_path)
-		quit(1)
-
-	if node == scene_root:
-		log_error("Cannot delete the root node")
-		quit(1)
-
-	var parent = node.get_parent()
-	parent.remove_child(node)
-	node.queue_free()
-
-	if save_scene_to_path(scene_root, params.scene_path):
-		print("Node '" + params.node_path + "' deleted successfully")
-	else:
-		log_error("Failed to save scene after deleting node")
-		quit(1)
-
-# Update a single property on a node
-func set_node_property(params):
-	printerr("Updating node property in scene: " + params.scene_path)
+# Delete one or more nodes from a scene (saves once)
+func delete_nodes(params):
+	printerr("Deleting nodes from scene: " + params.scene_path)
 
 	var scene_root = load_scene_instance(params.scene_path)
 	if not scene_root:
 		quit(1)
+		return
 
-	var node = find_node_by_path(scene_root, params.node_path)
-	if not node:
-		log_error("Node not found: " + params.node_path)
-		quit(1)
-
-	var property_name = params.property
-	var property_value = _coerce_property_value(params.value)
-
-	log_debug("Setting property '" + property_name + "' to: " + str(property_value))
-
-	node.set(property_name, property_value)
+	var node_paths: Array = params.node_paths
+	var results: Array = []
+	var any_deleted := false
 
-	if save_scene_to_path(scene_root, params.scene_path):
-		print("Property '" + property_name + "' updated successfully on node '" + params.node_path + "'")
-	else:
-		log_error("Failed to save scene after updating property")
-		quit(1)
+	for node_path in node_paths:
+		var entry = {"nodePath": node_path}
+		var node = find_node_by_path(scene_root, node_path)
+		if not node:
+			entry["error"] = "Node not found: " + node_path
+		elif node == scene_root:
+			entry["error"] = "Cannot delete the root node"
+		else:
+			var parent = node.get_parent()
+			parent.remove_child(node)
+			node.queue_free()
+			entry["success"] = true
+			any_deleted = true
+		results.append(entry)
+
+	if any_deleted:
+		if not save_scene_to_path(scene_root, params.scene_path):
+			print(JSON.stringify({"error": "Failed to save scene after deleting nodes", "results": results}))
+			return
 
-# Get all properties of a specific node
-func get_node_properties(params):
-	printerr("Getting node properties from scene: " + params.scene_path)
+	print(JSON.stringify({"results": results}))
 
+# Update one or more node properties in a single headless process (saves once)
+func set_node_properties(params: Dictionary) -> void:
 	var scene_root = load_scene_instance(params.scene_path)
 	if not scene_root:
-		quit(1)
-
-	var node = find_node_by_path(scene_root, params.node_path)
-	if not node:
-		log_error("Node not found: " + params.node_path)
-		quit(1)
+		print(JSON.stringify({"error": "Failed to load scene: " + params.scene_path, "results": []}))
+		return
 
-	var changed_only = params.has("changed_only") and params.changed_only
-	var properties = _collect_node_properties(node, changed_only)
+	var abort_on_error = params.get("abort_on_error", false)
+	var results: Array = []
+	var any_set := false
 
-	var result = {
-		"nodePath": params.node_path,
-		"nodeType": node.get_class(),
-		"properties": properties
-	}
+	for update in params.updates:
+		var result = {"nodePath": update.node_path, "property": update.property}
+		var node = find_node_by_path(scene_root, update.node_path)
+		if node == null:
+			result["error"] = "Node not found: " + update.node_path
+		elif not (update.property in node):
+			result["error"] = "Property '%s' does not exist on node of type '%s'" % [update.property, node.get_class()]
+		else:
+			node.set(update.property, _coerce_property_value(update.value))
+			result["success"] = true
+			any_set = true
+		results.append(result)
+		if abort_on_error and result.has("error"):
+			break
 
-	print(JSON.stringify(result))
+	if any_set:
+		if not save_scene_to_path(scene_root, params.scene_path):
+			print(JSON.stringify({"error": "Failed to save scene after updates", "results": results}))
+			return
 
-# List all child nodes under a parent
-func list_nodes(params):
-	printerr("Listing nodes in scene: " + params.scene_path)
+	print(JSON.stringify({"results": results}))
 
+# Get properties from one or more nodes in a single headless process (loads scene once)
+func get_node_properties(params: Dictionary) -> void:
 	var scene_root = load_scene_instance(params.scene_path)
 	if not scene_root:
-		quit(1)
-
-	var parent_path = "root"
-	if params.has("parent_path"):
-		parent_path = params.parent_path
+		print(JSON.stringify({"error": "Failed to load scene: " + params.scene_path, "results": []}))
+		return
 
-	var parent = find_node_by_path(scene_root, parent_path)
-	if not parent:
-		log_error("Parent node not found: " + parent_path)
-		quit(1)
+	var results: Array = []
+	# Class-name → default-instance cache. Reused across all nodes in this call
+	# so we don't instantiate a fresh default per node when changed_only is true.
+	var defaults_cache: Dictionary = {}
 
-	var children = []
-	for child in parent.get_children():
-		children.append({
-			"name": child.name,
-			"type": child.get_class(),
-			"childCount": child.get_child_count()
-		})
+	for node_spec in params.nodes:
+		var node_path = node_spec.get("node_path", "")
+		var changed_only = node_spec.get("changed_only", false)
+		var node = find_node_by_path(scene_root, node_path)
+		if node == null:
+			results.append({"nodePath": node_path, "error": "Node not found"})
+		else:
+			var props = _collect_node_properties(node, changed_only, defaults_cache)
+			results.append({"nodePath": node_path, "nodeType": node.get_class(), "properties": props})
 
-	var result = {
-		"parentPath": parent_path,
-		"parentType": parent.get_class(),
-		"children": children
-	}
+	# Free cached default instances; they were created via instantiate_class.
+	for klass in defaults_cache:
+		var inst = defaults_cache[klass]
+		if inst:
+			inst.free()
 
-	print(JSON.stringify(result))
+	print(JSON.stringify({"results": results}))
 
 # Get full hierarchical tree structure of a scene
 func get_scene_tree(params):
@@ -659,12 +590,21 @@ func get_scene_tree(params):
 	var scene_root = load_scene_instance(params.scene_path)
 	if not scene_root:
 		quit(1)
+		return
+
+	var tree_root = scene_root
+	if params.has("parent_path") and params.parent_path:
+		tree_root = find_node_by_path(scene_root, params.parent_path)
+		if not tree_root:
+			log_error("Parent node not found: " + str(params.parent_path))
+			quit(1)
+			return
 
 	var max_depth = -1
 	if params.has("max_depth"):
 		max_depth = int(params.max_depth)
 
-	var tree = build_tree_recursive(scene_root, "", 0, max_depth)
+	var tree = build_tree_recursive(tree_root, "", 0, max_depth)
 	print(JSON.stringify(tree))
 
 func build_tree_recursive(node: Node, path: String, depth: int = 0, max_depth: int = -1) -> Dictionary:
@@ -676,10 +616,9 @@ func build_tree_recursive(node: Node, path: String, depth: int = 0, max_depth: i
 			children.append(build_tree_recursive(child, node_path, depth + 1, max_depth))
 
 	var script_path = ""
-	if node.get_script():
-		var script = node.get_script()
-		if script.resource_path:
-			script_path = script.resource_path
+	var script = node.get_script()
+	if script and script.resource_path:
+		script_path = script.resource_path
 
 	return {
 		"name": node.name,
@@ -696,22 +635,26 @@ func attach_script(params):
 	var scene_root = load_scene_instance(params.scene_path)
 	if not scene_root:
 		quit(1)
+		return
 
 	var node = find_node_by_path(scene_root, params.node_path)
 	if not node:
 		log_error("Node not found: " + params.node_path)
 		quit(1)
+		return
 
 	var full_script_path = normalize_scene_path(params.script_path)
 
 	if not FileAccess.file_exists(full_script_path):
 		log_error("Script file does not exist: " + full_script_path)
 		quit(1)
+		return
 
 	var script = load(full_script_path)
 	if not script:
 		log_error("Failed to load script: " + full_script_path)
 		quit(1)
+		return
 
 	node.set_script(script)
 
@@ -720,6 +663,7 @@ func attach_script(params):
 	else:
 		log_error("Failed to save scene after attaching script")
 		quit(1)
+		return
 
 # ============================================
 # SIGNAL AND DUPLICATE OPERATIONS
@@ -728,15 +672,19 @@ func attach_script(params):
 # Duplicate a node and its children within a scene
 func duplicate_node(params):
 	var scene_root = load_scene_instance(params.scene_path)
-	if not scene_root: quit(1)
+	if not scene_root:
+		quit(1)
+		return
 
 	var node = find_node_by_path(scene_root, params.node_path)
 	if not node:
 		log_error("Node not found: " + params.node_path)
 		quit(1)
+		return
 	if node == scene_root:
 		log_error("Cannot duplicate the root node")
 		quit(1)
+		return
 
 	var duplicate = node.duplicate()
 	if params.has("new_name"):
@@ -750,33 +698,36 @@ func duplicate_node(params):
 		if not parent:
 			log_error("Target parent not found: " + params.target_parent_path)
 			quit(1)
+			return
 
 	parent.add_child(duplicate)
 	duplicate.owner = scene_root
-	# Recursively set owner on all descendants
-	for child in duplicate.get_children():
-		set_owner_recursive(child, scene_root)
+	# Iterative BFS to set owner on all descendants — avoids recursion depth.
+	var queue: Array = duplicate.get_children()
+	while not queue.is_empty():
+		var current = queue.pop_front()
+		current.owner = scene_root
+		queue.append_array(current.get_children())
 
 	if save_scene_to_path(scene_root, params.scene_path):
 		print("Node duplicated successfully as '" + duplicate.name + "'")
 	else:
 		log_error("Failed to save scene after duplicating node")
 		quit(1)
-
-func set_owner_recursive(node: Node, owner: Node):
-	node.owner = owner
-	for child in node.get_children():
-		set_owner_recursive(child, owner)
+		return
 
 # List signals defined on a node and their current connections
 func get_node_signals(params):
 	var scene_root = load_scene_instance(params.scene_path)
-	if not scene_root: quit(1)
+	if not scene_root:
+		quit(1)
+		return
 
 	var node = find_node_by_path(scene_root, params.node_path)
 	if not node:
 		log_error("Node not found: " + params.node_path)
 		quit(1)
+		return
 
 	var signals = []
 	for sig in node.get_signal_list():
@@ -802,55 +753,70 @@ func get_node_signals(params):
 # Connect a signal from one node to a method on another node
 func connect_signal(params):
 	var scene_root = load_scene_instance(params.scene_path)
-	if not scene_root: quit(1)
+	if not scene_root:
+		quit(1)
+		return
 
 	var source = find_node_by_path(scene_root, params.node_path)
 	if not source:
 		log_error("Source node not found: " + params.node_path)
 		quit(1)
+		return
 
 	var target = find_node_by_path(scene_root, params.target_node_path)
 	if not target:
 		log_error("Target node not found: " + params.target_node_path)
 		quit(1)
+		return
 
 	if not source.has_signal(params.signal):
 		log_error("Signal does not exist: " + params.signal + " on " + source.get_class())
 		quit(1)
+		return
 
 	if not target.has_method(params.method):
 		log_error("Method does not exist: " + params.method + " on " + target.get_class())
 		quit(1)
+		return
 
-	var err = source.connect(params.signal, Callable(target, params.method))
+	# CONNECT_PERSIST is required for the connection to be serialized into the
+	# packed scene; without it the connection is runtime-only and disappears on save.
+	var err = source.connect(params.signal, Callable(target, params.method), CONNECT_PERSIST)
 	if err != OK:
 		log_error("Failed to connect signal: " + str(err))
 		quit(1)
+		return
 
 	if save_scene_to_path(scene_root, params.scene_path):
 		print("Signal '" + params.signal + "' connected from '" + params.node_path + "' to '" + params.target_node_path + "." + params.method + "'")
 	else:
 		log_error("Failed to save scene after connecting signal")
 		quit(1)
+		return
 
 # Disconnect a signal connection between two nodes
 func disconnect_signal(params):
 	var scene_root = load_scene_instance(params.scene_path)
-	if not scene_root: quit(1)
+	if not scene_root:
+		quit(1)
+		return
 
 	var source = find_node_by_path(scene_root, params.node_path)
 	if not source:
 		log_error("Source node not found: " + params.node_path)
 		quit(1)
+		return
 
 	var target = find_node_by_path(scene_root, params.target_node_path)
 	if not target:
 		log_error("Target node not found: " + params.target_node_path)
 		quit(1)
+		return
 
 	if not source.is_connected(params.signal, Callable(target, params.method)):
 		log_error("Signal connection does not exist")
 		quit(1)
+		return
 
 	source.disconnect(params.signal, Callable(target, params.method))
 
@@ -859,6 +825,7 @@ func disconnect_signal(params):
 	else:
 		log_error("Failed to save scene after disconnecting signal")
 		quit(1)
+		return
 
 # ============================================
 # VALIDATE OPERATION
@@ -869,6 +836,7 @@ func validate_resource(params):
 	if not (params.has("script_path") or params.has("scene_path")):
 		log_error("validate_resource requires script_path or scene_path")
 		quit(1)
+		return
 	var result = _validate_single(params)
 	print(JSON.stringify({"valid": result.valid, "errors": result.errors}))
 
@@ -889,11 +857,20 @@ func _coerce_property_value(value):
 			return Color(value.r, value.g, value.b, a)
 	return value
 
-# Helper: collect node properties into a serializable Dictionary
-func _collect_node_properties(node: Node, changed_only: bool) -> Dictionary:
+# Helper: collect node properties into a serializable Dictionary. When
+# changed_only is true, compares each property against a default instance of
+# the node's class. The defaults_cache dict is keyed by class name so the
+# caller can reuse default instances across many nodes (caller is responsible
+# for freeing the cache when done).
+func _collect_node_properties(node: Node, changed_only: bool, defaults_cache: Dictionary) -> Dictionary:
 	var default_node = null
 	if changed_only:
-		default_node = instantiate_class(node.get_class())
+		var klass = node.get_class()
+		if defaults_cache.has(klass):
+			default_node = defaults_cache[klass]
+		else:
+			default_node = instantiate_class(klass)
+			defaults_cache[klass] = default_node
 
 	var properties = {}
 	var property_list = node.get_property_list()
@@ -928,9 +905,6 @@ func _collect_node_properties(node: Node, changed_only: bool) -> Dictionary:
 			else:
 				properties[prop_name] = str(value)
 
-	if default_node:
-		default_node.free()
-
 	return properties
 
 # Helper: validate a single target dict (script_path or scene_path)
@@ -958,46 +932,6 @@ func validate_batch(params: Dictionary) -> void:
 		results.append(_validate_single(target))
 	print(JSON.stringify({"results": results}))
 
-# Helper: add a node to a scene root without saving (returns error string or "")
-func _batch_add_node(scene_root: Node, op: Dictionary) -> String:
-	var parent_path = "root"
-	if op.has("parent_node_path"):
-		parent_path = op.parent_node_path
-	var parent = find_node_by_path(scene_root, parent_path)
-	if not parent:
-		return "Parent node not found: " + parent_path
-	if not op.has("node_type") or op.node_type == "":
-		return "node_type is required for add_node"
-	if not op.has("node_name") or op.node_name == "":
-		return "node_name is required for add_node"
-	var new_node = instantiate_class(op.node_type)
-	if not new_node:
-		return "Failed to instantiate node of type: " + op.node_type
-	new_node.name = op.node_name
-	if op.has("properties"):
-		for property in op.properties:
-			new_node.set(property, op.properties[property])
-	parent.add_child(new_node)
-	new_node.owner = scene_root
-	return ""
-
-# Helper: set a sprite texture without saving (returns error string or "")
-func _batch_load_sprite(scene_root: Node, op: Dictionary) -> String:
-	if not op.has("node_path") or op.node_path == "":
-		return "node_path is required for load_sprite"
-	if not op.has("texture_path") or op.texture_path == "":
-		return "texture_path is required for load_sprite"
-	var sprite_node = find_node_by_path(scene_root, op.node_path)
-	if not sprite_node:
-		return "Node not found: " + op.node_path
-	if not (sprite_node is Sprite2D or sprite_node is Sprite3D or sprite_node is TextureRect):
-		return "Node is not sprite-compatible: " + sprite_node.get_class()
-	var texture = load(normalize_scene_path(op.texture_path))
-	if not texture:
-		return "Failed to load texture: " + op.texture_path
-	sprite_node.texture = texture
-	return ""
-
 # Execute multiple scene operations in a single headless process
 # Scenes are loaded once and cached in memory; mutations accumulate until a save op
 func batch_scene_operations(params: Dictionary) -> void:
@@ -1028,18 +962,18 @@ func batch_scene_operations(params: Dictionary) -> void:
 				if scene_root == null:
 					result["error"] = "scene_path required for add_node"
 				else:
-					var err = _batch_add_node(scene_root, op)
-					if err != "":
-						result["error"] = err
+					var apply_result = _apply_add_node(scene_root, op)
+					if not apply_result.ok:
+						result["error"] = apply_result.error
 					else:
 						result["success"] = true
 			"load_sprite":
 				if scene_root == null:
 					result["error"] = "scene_path required for load_sprite"
 				else:
-					var err = _batch_load_sprite(scene_root, op)
-					if err != "":
-						result["error"] = err
+					var apply_result = _apply_load_sprite(scene_root, op)
+					if not apply_result.ok:
+						result["error"] = apply_result.error
 					else:
 						result["success"] = true
 			"save":
@@ -1067,51 +1001,3 @@ func batch_scene_operations(params: Dictionary) -> void:
 		save_scene_to_path(scene_cache[scene_path], scene_path)
 
 	print(JSON.stringify({"results": results}))
-
-# Update multiple node properties in a single headless process (loads and saves scene once)
-func batch_set_node_properties(params: Dictionary) -> void:
-	var scene_root = load_scene_instance(params.scene_path)
-	if not scene_root:
-		print(JSON.stringify({"error": "Failed to load scene: " + params.scene_path, "results": []}))
-		return
-
-	var abort_on_error = params.get("abort_on_error", false)
-	var results: Array = []
-
-	for update in params.updates:
-		var result = {"nodePath": update.node_path, "property": update.property}
-		var node = find_node_by_path(scene_root, update.node_path)
-		if node == null:
-			result["error"] = "Node not found: " + update.node_path
-		else:
-			node.set(update.property, _coerce_property_value(update.value))
-			result["success"] = true
-		results.append(result)
-		if abort_on_error and result.has("error"):
-			break
-
-	if save_scene_to_path(scene_root, params.scene_path):
-		print(JSON.stringify({"results": results}))
-	else:
-		print(JSON.stringify({"error": "Failed to save scene after batch updates", "partial_results": results}))
-
-# Get properties from multiple nodes in a single headless process (loads scene once)
-func batch_get_node_properties(params: Dictionary) -> void:
-	var scene_root = load_scene_instance(params.scene_path)
-	if not scene_root:
-		print(JSON.stringify({"error": "Failed to load scene: " + params.scene_path, "results": []}))
-		return
-
-	var results: Array = []
-
-	for node_spec in params.nodes:
-		var node_path = node_spec.get("node_path", "")
-		var changed_only = node_spec.get("changed_only", false)
-		var node = find_node_by_path(scene_root, node_path)
-		if node == null:
-			results.append({"nodePath": node_path, "error": "Node not found"})
-		else:
-			var props = _collect_node_properties(node, changed_only)
-			results.append({"nodePath": node_path, "nodeType": node.get_class(), "properties": props})
-
-	print(JSON.stringify({"results": results}))