breakpoint-mcp 1.82.1 → 1.84.0

package/addon/breakpoint_mcp/operations.gd

@@ -8,7 +8,7 @@ extends RefCounted
 
 const Codec := preload("res://addons/breakpoint_mcp/variant_json.gd")
 const Remedies := preload("res://addons/breakpoint_mcp/error_remedies.gd")
-const ADDON_VERSION := "1.12.0"
+const ADDON_VERSION := "1.15.0"
 
 var _plugin: EditorPlugin
 
@@ -373,6 +373,101 @@ func _path_of(root: Node, node: Node) -> String:
 	return String(root.get_path_to(node))
 
 
+## THE ONE PLACE A NODE JOINS THE EDITED SCENE.
+##
+## 🔴 `force_readable_name = true` IS LOAD-BEARING, NOT COSMETIC. Left at Godot's
+## default of false — which is what all twenty-two authoring tools did before 283 —
+## the engine answers ANY name collision with the machine form `@Type@N`, a name no
+## caller asked for and no human reads. Measured on 4.7: `node_add {name: "SFX"}`
+## twice returned "SFX" and then "@AudioStreamPlayer3D@19825", with no error and no
+## flag, so the caller's next call addressing "SFX" got `bad_path`. `node_duplicate`
+## had NO non-colliding case at all — a duplicate always collides with its source,
+## so "@Label@19826" was that tool's ONLY behaviour, where the editor's own Duplicate
+## gives "Label2". With `true` the engine takes the readable path the editor's Add
+## Node and Duplicate take, and the host's shipped promise that a name "defaults to
+## the class name" is true for the first time.
+##
+## 🔵 AND THE RENAME IS REPORTED, BECAUSE "SFX2" IS STILL NOT WHAT WAS ASKED FOR.
+## The returned Dictionary carries `coerced: true` and `requested` whenever the
+## engine's name differs — the shape `node_set_property` has answered with since
+## 1.82.0, so a caller parses one convention rather than two. `requested` is read
+## off the node itself rather than passed in, so a site cannot report a name it did
+## not actually ask the engine for.
+##
+## 🔴 A BARE `add_child` IN AN AUTHORING HANDLER IS THE DEFECT AGAIN, so this is the
+## only registration site in this file and `contract_check.py` check 31 refuses a
+## second one. A twenty-third authoring tool is covered by USING the seam, not by
+## somebody remembering the flag.
+func _commit_add(node: Node, parent: Node, root: Node, action: String, also_own: Array = []) -> Dictionary:
+	var requested := String(node.name)
+	var ur := _plugin.get_undo_redo()
+	ur.create_action(action)
+	ur.add_do_method(parent, "add_child", node, true)
+	ur.add_do_method(node, "set_owner", root)
+	for d in also_own:
+		ur.add_do_method(d, "set_owner", root)
+	ur.add_do_reference(node)
+	ur.add_undo_method(parent, "remove_child", node)
+	ur.commit_action()
+	var actual := String(node.name)
+	var out := {"path": _path_of(root, node), "name": actual}
+	if actual != requested:
+		out["coerced"] = true
+		out["requested"] = requested
+	return out
+
+
+## 🆕 284 — THE ONE PLACE THIS FILE WRITES A RESOURCE TO DISK.
+##
+## 🔴 MEASURED FROM A USER'S SIDE AGAINST A LIVE GODOT 4.7, AND IT IS 283 §1 ONE AXIS
+## OVER. 283 found that every tool taking a `name` handed it to `add_child` with
+## `force_readable_name` defaulted false, so a collision came back as `@Type@N` with no
+## flag. The collision here is a FILE and the answer was DELETION. Nine resources were
+## created, a sentinel line appended to each on disk, and each tool called a SECOND time
+## with identical arguments: every sentinel was gone, and every reply read `created` /
+## `saved` / `packed` — the same words, in the same shape, as the first call.
+##
+## `resource_create` overwrote an Environment a property had been set on, resetting it;
+## asked for a StandardMaterial3D at the same path it silently turned that resource into
+## a material, so anything referencing it as an Environment now holds the wrong type.
+## `scene_new` replaced a saved scene on disk while the editor's open copy still held the
+## node that had been added, so file and editor disagree and nothing says so.
+##
+## 🔴 AND THE PRODUCT GAVE FOUR ANSWERS TO ONE QUESTION. `filesystem_move` refused
+## `exists` with no way to force; the seven scaffold tools under `_mp_write_script`
+## refused `exists` unless `overwrite`; `filesystem_create_dir` succeeded and reported
+## `existed`; and the rest destroyed silently. `_mp_write_script` was already right, and
+## it was right because it is a SEAM — one function, one answer, seven tools. This is
+## that function for the twenty-four `ResourceSaver.save` sites, which were a roster:
+## 282 §2.3's rule, paid on a second uncounted population one session after the first.
+##
+## 🔵 THE TWO KINDS ARE A PROPERTY OF THE CALL SITE, NOT OF THE CALLER'S ARGUMENTS, and
+## that distinction is the whole design. `SAVE_NEW` means `to_path` is a DESTINATION the
+## caller named — a collision there is somebody else's file. `SAVE_BACK` means the path
+## is the resource's own home, loaded a few lines above and written back: overwriting is
+## not a hazard there, it IS the operation, and refusing it would break every
+## `*_set_property` tool on the surface. A flag the CALLER could set would let a caller
+## turn `theme_set_color` into a refusal; a constant at the SITE cannot.
+##
+## 🔵 `replaced` IS REPORTED ONLY WHEN IT HAPPENED — the shape `node_set_property` has
+## carried since 1.82.0 and `_commit_add` since 283: a field that appears when the engine
+## did something other than the plain thing, and is absent otherwise. *I created a file*
+## and *I overwrote your file because you asked me to* are not the same sentence.
+const SAVE_NEW := 0
+const SAVE_BACK := 1
+
+
+func _commit_save(res: Resource, to_path: String, params: Dictionary, kind: int,
+		flags: int = 0) -> Dictionary:
+	var existed := FileAccess.file_exists(to_path)
+	if kind == SAVE_NEW and existed and not bool(params.get("overwrite", false)):
+		return {"error": _err("exists", "File already exists (pass overwrite): %s" % to_path)}
+	var e := ResourceSaver.save(res, to_path, flags)
+	if e != OK:
+		return {"error": _err("save_failed", "ResourceSaver.save() returned %d" % e)}
+	return {"fields": {"replaced": true} if (existed and kind == SAVE_NEW) else {}}
+
+
 # ------------------------------------------------------------- handlers ------
 
 func _ping() -> Dictionary:
@@ -542,11 +637,11 @@ func _scene_new(params: Dictionary) -> Dictionary:
 	var e := packed.pack(root)
 	if e != OK:
 		return _err("pack_failed", "PackedScene.pack() returned %d" % e)
-	e = ResourceSaver.save(packed, path)
-	if e != OK:
-		return _err("save_failed", "ResourceSaver.save() returned %d" % e)
+	var saved := _commit_save(packed, path, params, SAVE_NEW)
+	if saved.has("error"):
+		return saved["error"]
 	EditorInterface.open_scene_from_path(path)
-	return _ok({"created": path, "root_type": root_type})
+	return _ok({"created": path, "root_type": root_type}.merged(saved["fields"]))
 
 
 func _node_add(params: Dictionary) -> Dictionary:
@@ -561,14 +656,9 @@ func _node_add(params: Dictionary) -> Dictionary:
 		return _err("bad_type", "Cannot instantiate class: %s" % type)
 	var node: Node = ClassDB.instantiate(type)
 	node.name = String(params.get("name", type))
-	var ur := _plugin.get_undo_redo()
-	ur.create_action("Breakpoint: add %s" % node.name)
-	ur.add_do_method(parent, "add_child", node)
-	ur.add_do_method(node, "set_owner", root)
-	ur.add_do_reference(node)
-	ur.add_undo_method(parent, "remove_child", node)
-	ur.commit_action()
-	return _ok({"path": _path_of(root, node), "name": String(node.name), "type": type})
+	var added := _commit_add(node, parent, root, "Breakpoint: add %s" % node.name)
+	added["type"] = type
+	return _ok(added)
 
 
 func _node_delete(params: Dictionary) -> Dictionary:
@@ -1101,16 +1191,9 @@ func _node_duplicate(params: Dictionary) -> Dictionary:
 	var dup: Node = node.duplicate()
 	if params.has("name"):
 		dup.name = String(params.get("name"))
-	var ur := _plugin.get_undo_redo()
-	ur.create_action("Breakpoint: duplicate %s" % node.name)
-	ur.add_do_method(parent, "add_child", dup)
-	ur.add_do_method(dup, "set_owner", root)
-	for d in _descendants(dup):
-		ur.add_do_method(d, "set_owner", root)
-	ur.add_do_reference(dup)
-	ur.add_undo_method(parent, "remove_child", dup)
-	ur.commit_action()
-	return _ok({"path": _path_of(root, dup), "name": String(dup.name), "type": dup.get_class()})
+	var added := _commit_add(dup, parent, root, "Breakpoint: duplicate %s" % node.name, _descendants(dup))
+	added["type"] = dup.get_class()
+	return _ok(added)
 
 
 func _node_get_children(params: Dictionary) -> Dictionary:
@@ -1221,14 +1304,10 @@ func _node_instantiate_scene(params: Dictionary) -> Dictionary:
 		return _err("instantiate_failed", "Could not instantiate %s" % scene_path)
 	if params.has("name"):
 		inst.name = String(params.get("name"))
-	var ur := _plugin.get_undo_redo()
-	ur.create_action("Breakpoint: instance scene %s" % scene_path)
-	ur.add_do_method(parent, "add_child", inst)
-	ur.add_do_method(inst, "set_owner", root)
-	ur.add_do_reference(inst)
-	ur.add_undo_method(parent, "remove_child", inst)
-	ur.commit_action()
-	return _ok({"path": _path_of(root, inst), "name": String(inst.name), "type": inst.get_class(), "scene": scene_path})
+	var added := _commit_add(inst, parent, root, "Breakpoint: instance scene %s" % scene_path)
+	added["type"] = inst.get_class()
+	added["scene"] = scene_path
+	return _ok(added)
 
 
 func _node_move_child(params: Dictionary) -> Dictionary:
@@ -1569,11 +1648,11 @@ func _scene_pack(params: Dictionary) -> Dictionary:
 	if e != OK:
 		dup.free()
 		return _err("pack_failed", "PackedScene.pack() returned %d" % e)
-	e = ResourceSaver.save(packed, to_path)
+	var saved := _commit_save(packed, to_path, params, SAVE_NEW)
 	dup.free()
-	if e != OK:
-		return _err("save_failed", "ResourceSaver.save() returned %d" % e)
-	return _ok({"packed": to_path, "branch": _path_of(root, branch)})
+	if saved.has("error"):
+		return saved["error"]
+	return _ok({"packed": to_path, "branch": _path_of(root, branch)}.merged(saved["fields"]))
 
 
 func _scene_save_as(params: Dictionary) -> Dictionary:
@@ -1779,10 +1858,10 @@ func _resource_create(params: Dictionary) -> Dictionary:
 		return _err("create_failed", "Could not instantiate %s" % cls)
 	for key in params.get("properties", {}):
 		res.set(String(key), Codec.decode(params["properties"][key]))
-	var e := ResourceSaver.save(res, to_path)
-	if e != OK:
-		return _err("save_failed", "ResourceSaver.save() returned %d" % e)
-	return _ok({"created": to_path, "type": cls})
+	var saved := _commit_save(res, to_path, params, SAVE_NEW)
+	if saved.has("error"):
+		return saved["error"]
+	return _ok({"created": to_path, "type": cls}.merged(saved["fields"]))
 
 
 func _resource_load(params: Dictionary) -> Dictionary:
@@ -1813,10 +1892,15 @@ func _resource_save(params: Dictionary) -> Dictionary:
 	if res == null:
 		return _err("load_failed", "Could not load resource: %s" % from_path)
 	var flags := int(params.get("flags", 0))
-	var e := ResourceSaver.save(res, to_path, flags)
-	if e != OK:
-		return _err("save_failed", "ResourceSaver.save() returned %d" % e)
-	return _ok({"saved": to_path, "from": from_path})
+	# 🔵 THE KIND IS DERIVED HERE AND NOWHERE ELSE: `to_path` DEFAULTS to `from_path`,
+	# so this one tool is a save-back when the caller named no destination and a
+	# create when they did. Reading it off the arguments at the site is the honest
+	# version; a constant would be wrong half the time.
+	var kind := SAVE_BACK if to_path == from_path else SAVE_NEW
+	var saved := _commit_save(res, to_path, params, kind, flags)
+	if saved.has("error"):
+		return saved["error"]
+	return _ok({"saved": to_path, "from": from_path}.merged(saved["fields"]))
 
 
 func _resource_duplicate(params: Dictionary) -> Dictionary:
@@ -1833,10 +1917,10 @@ func _resource_duplicate(params: Dictionary) -> Dictionary:
 	var dup := res.duplicate(deep)
 	if dup == null:
 		return _err("duplicate_failed", "Could not duplicate resource")
-	var e := ResourceSaver.save(dup, to_path)
-	if e != OK:
-		return _err("save_failed", "ResourceSaver.save() returned %d" % e)
-	return _ok({"duplicated": to_path, "from": from_path, "deep": deep})
+	var saved := _commit_save(dup, to_path, params, SAVE_NEW)
+	if saved.has("error"):
+		return saved["error"]
+	return _ok({"duplicated": to_path, "from": from_path, "deep": deep}.merged(saved["fields"]))
 
 
 func _resource_get_property(params: Dictionary) -> Dictionary:
@@ -1863,9 +1947,9 @@ func _resource_set_property(params: Dictionary) -> Dictionary:
 	if prop == "":
 		return _err("bad_params", "Missing 'property'")
 	res.set(prop, Codec.decode(params.get("value")))
-	var e := ResourceSaver.save(res, path)
-	if e != OK:
-		return _err("save_failed", "ResourceSaver.save() returned %d" % e)
+	var saved := _commit_save(res, path, params, SAVE_BACK)
+	if saved.has("error"):
+		return saved["error"]
 	return _ok({"path": path, "property": prop, "value": Codec.encode(res.get(prop))})
 
 
@@ -2102,10 +2186,11 @@ func _asset_gen_placeholder(params: Dictionary) -> Dictionary:
 			# pipeline) — the placeholder must be usable synchronously. External
 			# formats (a real backend's .png) go through asset.import instead.
 			var tex := ImageTexture.create_from_image(img)
-			var e := ResourceSaver.save(tex, to_path)
-			if e != OK:
-				return _err("save_failed", "ResourceSaver.save() returned %d" % e)
+			var saved_e := _commit_save(tex, to_path, params, SAVE_NEW)
+			if saved_e.has("error"):
+				return saved_e["error"]
 			var desc := _import_and_describe(to_path)
+			desc.merge(saved_e["fields"])
 			desc["kind"] = kind
 			desc["width"] = w
 			desc["height"] = h
@@ -2114,10 +2199,11 @@ func _asset_gen_placeholder(params: Dictionary) -> Dictionary:
 		"audio_sfx":
 			var dur := clampi(int(params.get("duration_ms", 300)), 20, 5000)
 			var stream := _gen_audio(seed_hash, dur)
-			var e2 := ResourceSaver.save(stream, to_path)
-			if e2 != OK:
-				return _err("save_failed", "ResourceSaver.save() returned %d" % e2)
+			var saved_e2 := _commit_save(stream, to_path, params, SAVE_NEW)
+			if saved_e2.has("error"):
+				return saved_e2["error"]
 			var desc2 := _import_and_describe(to_path)
+			desc2.merge(saved_e2["fields"])
 			desc2["kind"] = kind
 			desc2["duration_ms"] = dur
 			desc2["format"] = "AudioStreamWAV"
@@ -2125,10 +2211,11 @@ func _asset_gen_placeholder(params: Dictionary) -> Dictionary:
 		"model":
 			var shape := String(params.get("shape", "box"))
 			var mesh := _gen_mesh(shape, seed_hash)
-			var e3 := ResourceSaver.save(mesh, to_path)
-			if e3 != OK:
-				return _err("save_failed", "ResourceSaver.save() returned %d" % e3)
+			var saved_e3 := _commit_save(mesh, to_path, params, SAVE_NEW)
+			if saved_e3.has("error"):
+				return saved_e3["error"]
 			var desc3 := _import_and_describe(to_path)
+			desc3.merge(saved_e3["fields"])
 			desc3["kind"] = kind
 			desc3["shape"] = shape
 			desc3["format"] = mesh.get_class()
@@ -2282,14 +2369,9 @@ func _anim_player_create(params: Dictionary) -> Dictionary:
 	var node := AnimationPlayer.new()
 	node.name = String(params.get("name", "AnimationPlayer"))
 	node.add_animation_library("", AnimationLibrary.new())
-	var ur := _plugin.get_undo_redo()
-	ur.create_action("Breakpoint: add AnimationPlayer %s" % node.name)
-	ur.add_do_method(parent, "add_child", node)
-	ur.add_do_method(node, "set_owner", root)
-	ur.add_do_reference(node)
-	ur.add_undo_method(parent, "remove_child", node)
-	ur.commit_action()
-	return _ok({"path": _path_of(root, node), "name": String(node.name), "type": "AnimationPlayer"})
+	var added := _commit_add(node, parent, root, "Breakpoint: add AnimationPlayer %s" % node.name)
+	added["type"] = "AnimationPlayer"
+	return _ok(added)
 
 
 func _anim_create(params: Dictionary) -> Dictionary:
@@ -2607,14 +2689,12 @@ func _anim_tree_create(params: Dictionary) -> Dictionary:
 	if anim_player_path != "":
 		node.set("anim_player", NodePath(anim_player_path))
 	node.set("active", bool(params.get("active", false)))
-	var ur := _plugin.get_undo_redo()
-	ur.create_action("Breakpoint: add AnimationTree %s" % node.name)
-	ur.add_do_method(parent, "add_child", node)
-	ur.add_do_method(node, "set_owner", root)
-	ur.add_do_reference(node)
-	ur.add_undo_method(parent, "remove_child", node)
-	ur.commit_action()
-	return _ok({"path": _path_of(root, node), "name": String(node.name), "type": "AnimationTree", "root_type": rt, "anim_player": anim_player_path, "active": bool(node.get("active"))})
+	var added := _commit_add(node, parent, root, "Breakpoint: add AnimationTree %s" % node.name)
+	added["type"] = "AnimationTree"
+	added["root_type"] = rt
+	added["anim_player"] = anim_player_path
+	added["active"] = bool(node.get("active"))
+	return _ok(added)
 
 
 func _anim_tree_add_node(params: Dictionary) -> Dictionary:
@@ -2760,11 +2840,11 @@ func _tileset_create(params: Dictionary) -> Dictionary:
 	var ts := TileSet.new()
 	if params.has("tile_size"):
 		ts.set("tile_size", _to_vec2i(params.get("tile_size")))
-	var e := ResourceSaver.save(ts, to_path)
-	if e != OK:
-		return _err("save_failed", "ResourceSaver.save() returned %d" % e)
+	var saved := _commit_save(ts, to_path, params, SAVE_NEW)
+	if saved.has("error"):
+		return saved["error"]
 	var tsz: Vector2i = ts.get("tile_size")
-	return _ok({"created": to_path, "tile_size": [tsz.x, tsz.y]})
+	return _ok({"created": to_path, "tile_size": [tsz.x, tsz.y]}.merged(saved["fields"]))
 
 
 func _tileset_add_source(params: Dictionary) -> Dictionary:
@@ -2789,9 +2869,9 @@ func _tileset_add_source(params: Dictionary) -> Dictionary:
 	if params.has("separation"):
 		atlas.set("separation", _to_vec2i(params.get("separation")))
 	var assigned: int = ts.add_source(atlas, int(params.get("source_id", -1)))
-	var e := ResourceSaver.save(ts, tileset_path)
-	if e != OK:
-		return _err("save_failed", "ResourceSaver.save() returned %d" % e)
+	var saved := _commit_save(ts, tileset_path, params, SAVE_BACK)
+	if saved.has("error"):
+		return saved["error"]
 	return _ok({"tileset": tileset_path, "source_id": assigned, "texture": texture_path, "texture_region_size": [region.x, region.y], "source_count": ts.get_source_count()})
 
 
@@ -2813,9 +2893,9 @@ func _tileset_add_tile(params: Dictionary) -> Dictionary:
 	if params.has("size"):
 		size = _to_vec2i(params.get("size"))
 	src.create_tile(coords, size)
-	var e := ResourceSaver.save(ts, tileset_path)
-	if e != OK:
-		return _err("save_failed", "ResourceSaver.save() returned %d" % e)
+	var saved := _commit_save(ts, tileset_path, params, SAVE_BACK)
+	if saved.has("error"):
+		return saved["error"]
 	return _ok({"tileset": tileset_path, "source_id": sid, "atlas_coords": [coords.x, coords.y], "size": [size.x, size.y], "tiles_count": src.get_tiles_count()})
 
 
@@ -2850,9 +2930,9 @@ func _tileset_set_tile_collision(params: Dictionary) -> Dictionary:
 	var one_way := bool(params.get("one_way", false))
 	if params.has("one_way"):
 		td.set_collision_polygon_one_way(layer, poly_index, one_way)
-	var e := ResourceSaver.save(ts, tileset_path)
-	if e != OK:
-		return _err("save_failed", "ResourceSaver.save() returned %d" % e)
+	var saved := _commit_save(ts, tileset_path, params, SAVE_BACK)
+	if saved.has("error"):
+		return saved["error"]
 	return _ok({"tileset": tileset_path, "source_id": sid, "atlas_coords": [coords.x, coords.y], "physics_layer": layer, "polygon_index": poly_index, "points": poly.size(), "one_way": one_way})
 
 
@@ -2886,14 +2966,10 @@ func _tilemaplayer_create(params: Dictionary) -> Dictionary:
 		if ts == null:
 			return _err("not_found", "TileSet not found: %s" % tileset_path)
 		layer.tile_set = ts
-	var ur := _plugin.get_undo_redo()
-	ur.create_action("Breakpoint: add TileMapLayer %s" % layer.name)
-	ur.add_do_method(parent, "add_child", layer)
-	ur.add_do_method(layer, "set_owner", root)
-	ur.add_do_reference(layer)
-	ur.add_undo_method(parent, "remove_child", layer)
-	ur.commit_action()
-	return _ok({"path": _path_of(root, layer), "name": String(layer.name), "type": "TileMapLayer", "tile_set": tileset_path})
+	var added := _commit_add(layer, parent, root, "Breakpoint: add TileMapLayer %s" % layer.name)
+	added["type"] = "TileMapLayer"
+	added["tile_set"] = tileset_path
+	return _ok(added)
 
 
 func _tilemap_set_cell(params: Dictionary) -> Dictionary:
@@ -3041,14 +3117,11 @@ func _body_create(params: Dictionary) -> Dictionary:
 		return _err("bad_type", "Cannot instantiate class: %s" % cls)
 	var node: Node = ClassDB.instantiate(cls)
 	node.name = String(params.get("name", cls))
-	var ur := _plugin.get_undo_redo()
-	ur.create_action("Breakpoint: add %s" % node.name)
-	ur.add_do_method(parent, "add_child", node)
-	ur.add_do_method(node, "set_owner", root)
-	ur.add_do_reference(node)
-	ur.add_undo_method(parent, "remove_child", node)
-	ur.commit_action()
-	return _ok({"path": _path_of(root, node), "name": String(node.name), "type": cls, "body": kind, "dim": ("3d" if dim3 else "2d")})
+	var added := _commit_add(node, parent, root, "Breakpoint: add %s" % node.name)
+	added["type"] = cls
+	added["body"] = kind
+	added["dim"] = ("3d" if dim3 else "2d")
+	return _ok(added)
 
 
 func _make_collision_shape(kind: String, dim3: bool, params: Dictionary):
@@ -3118,14 +3191,12 @@ func _collisionshape_add(params: Dictionary) -> Dictionary:
 		cs2.set("shape", shape_res)
 		node = cs2
 	node.name = String(params.get("name", node.get_class()))
-	var ur := _plugin.get_undo_redo()
-	ur.create_action("Breakpoint: add %s" % node.name)
-	ur.add_do_method(parent, "add_child", node)
-	ur.add_do_method(node, "set_owner", root)
-	ur.add_do_reference(node)
-	ur.add_undo_method(parent, "remove_child", node)
-	ur.commit_action()
-	return _ok({"path": _path_of(root, node), "name": String(node.name), "type": node.get_class(), "shape": kind, "shape_class": shape_res.get_class(), "dim": ("3d" if dim3 else "2d")})
+	var added := _commit_add(node, parent, root, "Breakpoint: add %s" % node.name)
+	added["type"] = node.get_class()
+	added["shape"] = kind
+	added["shape_class"] = shape_res.get_class()
+	added["dim"] = ("3d" if dim3 else "2d")
+	return _ok(added)
 
 
 func _body_set_collision_layer(params: Dictionary) -> Dictionary:
@@ -3282,14 +3353,13 @@ func _joint_create(params: Dictionary) -> Dictionary:
 		node.set("node_a", NodePath(String(params.get("node_a"))))
 	if params.has("node_b"):
 		node.set("node_b", NodePath(String(params.get("node_b"))))
-	var ur := _plugin.get_undo_redo()
-	ur.create_action("Breakpoint: add %s" % node.name)
-	ur.add_do_method(parent, "add_child", node)
-	ur.add_do_method(node, "set_owner", root)
-	ur.add_do_reference(node)
-	ur.add_undo_method(parent, "remove_child", node)
-	ur.commit_action()
-	return _ok({"path": _path_of(root, node), "name": String(node.name), "type": cls, "joint": kind, "dim": ("3d" if dim3 else "2d"), "node_a": String(node.get("node_a")), "node_b": String(node.get("node_b"))})
+	var added := _commit_add(node, parent, root, "Breakpoint: add %s" % node.name)
+	added["type"] = cls
+	added["joint"] = kind
+	added["dim"] = ("3d" if dim3 else "2d")
+	added["node_a"] = String(node.get("node_a"))
+	added["node_b"] = String(node.get("node_b"))
+	return _ok(added)
 
 
 func _joint_set_bodies(params: Dictionary) -> Dictionary:
@@ -3341,14 +3411,11 @@ func _collisionpolygon_add(params: Dictionary) -> Dictionary:
 			c2.set("build_mode", bm)
 		node = c2
 	node.name = String(params.get("name", node.get_class()))
-	var ur := _plugin.get_undo_redo()
-	ur.create_action("Breakpoint: add %s" % node.name)
-	ur.add_do_method(parent, "add_child", node)
-	ur.add_do_method(node, "set_owner", root)
-	ur.add_do_reference(node)
-	ur.add_undo_method(parent, "remove_child", node)
-	ur.commit_action()
-	return _ok({"path": _path_of(root, node), "name": String(node.name), "type": node.get_class(), "dim": ("3d" if dim3 else "2d"), "points": pts.size()})
+	var added := _commit_add(node, parent, root, "Breakpoint: add %s" % node.name)
+	added["type"] = node.get_class()
+	added["dim"] = ("3d" if dim3 else "2d")
+	added["points"] = pts.size()
+	return _ok(added)
 
 
 func _rigidbody_set_properties(params: Dictionary) -> Dictionary:
@@ -3461,14 +3528,13 @@ func _particles_create(params: Dictionary) -> Dictionary:
 		node.set("lifetime", float(params.get("lifetime")))
 	if params.has("emitting"):
 		node.set("emitting", bool(params.get("emitting")))
-	var ur := _plugin.get_undo_redo()
-	ur.create_action("Breakpoint: add %s" % node.name)
-	ur.add_do_method(parent, "add_child", node)
-	ur.add_do_method(node, "set_owner", root)
-	ur.add_do_reference(node)
-	ur.add_undo_method(parent, "remove_child", node)
-	ur.commit_action()
-	return _ok({"path": _path_of(root, node), "name": String(node.name), "type": node.get_class(), "dim": ("3d" if dim3 else "2d"), "amount": int(node.get("amount")), "lifetime": float(node.get("lifetime")), "emitting": bool(node.get("emitting"))})
+	var added := _commit_add(node, parent, root, "Breakpoint: add %s" % node.name)
+	added["type"] = node.get_class()
+	added["dim"] = ("3d" if dim3 else "2d")
+	added["amount"] = int(node.get("amount"))
+	added["lifetime"] = float(node.get("lifetime"))
+	added["emitting"] = bool(node.get("emitting"))
+	return _ok(added)
 
 
 func _particles_set_process_material(params: Dictionary) -> Dictionary:
@@ -3621,10 +3687,10 @@ func _shader_create(params: Dictionary) -> Dictionary:
 	var sh := Shader.new()
 	if params.has("code"):
 		sh.code = String(params.get("code"))
-	var e := ResourceSaver.save(sh, to_path)
-	if e != OK:
-		return _err("save_failed", "ResourceSaver.save() returned %d" % e)
-	return _ok({"created": to_path, "type": "Shader", "code_length": sh.code.length()})
+	var saved := _commit_save(sh, to_path, params, SAVE_NEW)
+	if saved.has("error"):
+		return saved["error"]
+	return _ok({"created": to_path, "type": "Shader", "code_length": sh.code.length()}.merged(saved["fields"]))
 
 
 func _shader_set_code(params: Dictionary) -> Dictionary:
@@ -3638,9 +3704,9 @@ func _shader_set_code(params: Dictionary) -> Dictionary:
 		return _err("bad_type", "%s is not a Shader" % path)
 	var sh := res as Shader
 	sh.code = String(params.get("code"))
-	var e := ResourceSaver.save(sh, path)
-	if e != OK:
-		return _err("save_failed", "ResourceSaver.save() returned %d" % e)
+	var saved := _commit_save(sh, path, params, SAVE_BACK)
+	if saved.has("error"):
+		return saved["error"]
 	return _ok({"path": path, "code_length": sh.code.length()})
 
 
@@ -3769,14 +3835,14 @@ func _audio_player_create(params: Dictionary) -> Dictionary:
 		if not (sres is AudioStream):
 			return _err("bad_type", "%s is not an AudioStream" % stream_path)
 		node.set("stream", sres as AudioStream)
-	var ur := _plugin.get_undo_redo()
-	ur.create_action("Breakpoint: add %s" % node.name)
-	ur.add_do_method(parent, "add_child", node)
-	ur.add_do_method(node, "set_owner", root)
-	ur.add_do_reference(node)
-	ur.add_undo_method(parent, "remove_child", node)
-	ur.commit_action()
-	return _ok({"path": _path_of(root, node), "name": String(node.name), "type": node.get_class(), "dim": dim, "autoplay": bool(node.get("autoplay")), "volume_db": float(node.get("volume_db")), "bus": String(node.get("bus")), "stream_path": stream_path})
+	var added := _commit_add(node, parent, root, "Breakpoint: add %s" % node.name)
+	added["type"] = node.get_class()
+	added["dim"] = dim
+	added["autoplay"] = bool(node.get("autoplay"))
+	added["volume_db"] = float(node.get("volume_db"))
+	added["bus"] = String(node.get("bus"))
+	added["stream_path"] = stream_path
+	return _ok(added)
 
 
 func _audio_set_stream(params: Dictionary) -> Dictionary:
@@ -3847,10 +3913,10 @@ func _audio_set_bus_layout(params: Dictionary) -> Dictionary:
 	if not to_path.begins_with("res://"):
 		return _err("bad_params", "'to_path' must be a res:// path")
 	var layout = AudioServer.generate_bus_layout()
-	var e := ResourceSaver.save(layout, to_path)
-	if e != OK:
-		return _err("save_failed", "ResourceSaver.save() returned %d" % e)
-	return _ok({"saved": to_path, "bus_count": AudioServer.get_bus_count()})
+	var saved := _commit_save(layout, to_path, params, SAVE_NEW)
+	if saved.has("error"):
+		return saved["error"]
+	return _ok({"saved": to_path, "bus_count": AudioServer.get_bus_count()}.merged(saved["fields"]))
 
 
 # ---------------------------------------------------------------- Group G: UI / control / theming ----
@@ -3876,14 +3942,9 @@ func _control_create(params: Dictionary) -> Dictionary:
 	node.name = String(params.get("name", type))
 	if params.has("text") and _has_property(node, "text"):
 		node.set("text", String(params.get("text")))
-	var ur := _plugin.get_undo_redo()
-	ur.create_action("Breakpoint: add %s" % node.name)
-	ur.add_do_method(parent, "add_child", node)
-	ur.add_do_method(node, "set_owner", root)
-	ur.add_do_reference(node)
-	ur.add_undo_method(parent, "remove_child", node)
-	ur.commit_action()
-	return _ok({"path": _path_of(root, node), "name": String(node.name), "type": type})
+	var added := _commit_add(node, parent, root, "Breakpoint: add %s" % node.name)
+	added["type"] = type
+	return _ok(added)
 
 
 func _container_add_child(params: Dictionary) -> Dictionary:
@@ -3902,14 +3963,10 @@ func _container_add_child(params: Dictionary) -> Dictionary:
 		return _err("bad_type", "%s is not a Control subclass" % type)
 	var node: Node = ClassDB.instantiate(type)
 	node.name = String(params.get("name", type))
-	var ur := _plugin.get_undo_redo()
-	ur.create_action("Breakpoint: add %s to container" % node.name)
-	ur.add_do_method(parent, "add_child", node)
-	ur.add_do_method(node, "set_owner", root)
-	ur.add_do_reference(node)
-	ur.add_undo_method(parent, "remove_child", node)
-	ur.commit_action()
-	return _ok({"path": _path_of(root, node), "name": String(node.name), "type": type, "container": _path_of(root, parent)})
+	var added := _commit_add(node, parent, root, "Breakpoint: add %s to container" % node.name)
+	added["type"] = type
+	added["container"] = _path_of(root, parent)
+	return _ok(added)
 
 
 func _control_set_anchors(params: Dictionary) -> Dictionary:
@@ -4043,10 +4100,10 @@ func _theme_create(params: Dictionary) -> Dictionary:
 	if not to_path.begins_with("res://"):
 		return _err("bad_params", "'to_path' must be a res:// path")
 	var theme := Theme.new()
-	var e := ResourceSaver.save(theme, to_path)
-	if e != OK:
-		return _err("save_failed", "ResourceSaver.save() returned %d" % e)
-	return _ok({"created": to_path, "type": "Theme"})
+	var saved := _commit_save(theme, to_path, params, SAVE_NEW)
+	if saved.has("error"):
+		return saved["error"]
+	return _ok({"created": to_path, "type": "Theme"}.merged(saved["fields"]))
 
 
 func _theme_set_color(params: Dictionary) -> Dictionary:
@@ -4060,9 +4117,9 @@ func _theme_set_color(params: Dictionary) -> Dictionary:
 		return _err("bad_params", "Missing 'name' or 'theme_type'")
 	var col := _to_color(params.get("color"))
 	theme.set_color(iname, ttype, col)
-	var e := ResourceSaver.save(theme, path)
-	if e != OK:
-		return _err("save_failed", "ResourceSaver.save() returned %d" % e)
+	var saved := _commit_save(theme, path, params, SAVE_BACK)
+	if saved.has("error"):
+		return saved["error"]
 	return _ok({"path": path, "name": iname, "theme_type": ttype, "color": [col.r, col.g, col.b, col.a]})
 
 
@@ -4082,9 +4139,9 @@ func _theme_set_font(params: Dictionary) -> Dictionary:
 	if not (fres is Font):
 		return _err("bad_type", "%s is not a Font" % font_path)
 	theme.set_font(iname, ttype, fres as Font)
-	var e := ResourceSaver.save(theme, path)
-	if e != OK:
-		return _err("save_failed", "ResourceSaver.save() returned %d" % e)
+	var saved := _commit_save(theme, path, params, SAVE_BACK)
+	if saved.has("error"):
+		return saved["error"]
 	return _ok({"path": path, "name": iname, "theme_type": ttype, "font_path": font_path})
 
 
@@ -4104,9 +4161,9 @@ func _theme_set_stylebox(params: Dictionary) -> Dictionary:
 	if not (sres is StyleBox):
 		return _err("bad_type", "%s is not a StyleBox" % sb_path)
 	theme.set_stylebox(iname, ttype, sres as StyleBox)
-	var e := ResourceSaver.save(theme, path)
-	if e != OK:
-		return _err("save_failed", "ResourceSaver.save() returned %d" % e)
+	var saved := _commit_save(theme, path, params, SAVE_BACK)
+	if saved.has("error"):
+		return saved["error"]
 	return _ok({"path": path, "name": iname, "theme_type": ttype, "stylebox_path": sb_path})
 
 
@@ -4123,9 +4180,9 @@ func _theme_set_constant(params: Dictionary) -> Dictionary:
 		return _err("bad_params", "Missing 'value'")
 	var val := int(params.get("value"))
 	theme.set_constant(iname, ttype, val)
-	var e := ResourceSaver.save(theme, path)
-	if e != OK:
-		return _err("save_failed", "ResourceSaver.save() returned %d" % e)
+	var saved := _commit_save(theme, path, params, SAVE_BACK)
+	if saved.has("error"):
+		return saved["error"]
 	return _ok({"path": path, "name": iname, "theme_type": ttype, "value": val})
 
 
@@ -4216,14 +4273,10 @@ func _meshinstance_create(params: Dictionary) -> Dictionary:
 	node.name = String(params.get("name", "MeshInstance3D"))
 	if mesh_res != null:
 		node.mesh = mesh_res
-	var ur := _plugin.get_undo_redo()
-	ur.create_action("Breakpoint: add %s" % node.name)
-	ur.add_do_method(parent, "add_child", node)
-	ur.add_do_method(node, "set_owner", root)
-	ur.add_do_reference(node)
-	ur.add_undo_method(parent, "remove_child", node)
-	ur.commit_action()
-	return _ok({"path": _path_of(root, node), "name": String(node.name), "type": "MeshInstance3D", "mesh_path": mesh_path})
+	var added := _commit_add(node, parent, root, "Breakpoint: add %s" % node.name)
+	added["type"] = "MeshInstance3D"
+	added["mesh_path"] = mesh_path
+	return _ok(added)
 
 
 func _mesh_set_surface_material(params: Dictionary) -> Dictionary:
@@ -4277,10 +4330,10 @@ func _primitive_mesh_create(params: Dictionary) -> Dictionary:
 	var mesh: Mesh = ClassDB.instantiate(cls)
 	if mesh == null:
 		return _err("create_failed", "Could not instantiate %s" % cls)
-	var e := ResourceSaver.save(mesh, to_path)
-	if e != OK:
-		return _err("save_failed", "ResourceSaver.save() returned %d" % e)
-	return _ok({"created": to_path, "type": cls, "shape": shape})
+	var saved := _commit_save(mesh, to_path, params, SAVE_NEW)
+	if saved.has("error"):
+		return saved["error"]
+	return _ok({"created": to_path, "type": cls, "shape": shape}.merged(saved["fields"]))
 
 
 func _light_create(params: Dictionary) -> Dictionary:
@@ -4297,14 +4350,10 @@ func _light_create(params: Dictionary) -> Dictionary:
 	var cls := String(classes[kind])
 	var node: Node = ClassDB.instantiate(cls)
 	node.name = String(params.get("name", cls))
-	var ur := _plugin.get_undo_redo()
-	ur.create_action("Breakpoint: add %s" % node.name)
-	ur.add_do_method(parent, "add_child", node)
-	ur.add_do_method(node, "set_owner", root)
-	ur.add_do_reference(node)
-	ur.add_undo_method(parent, "remove_child", node)
-	ur.commit_action()
-	return _ok({"path": _path_of(root, node), "name": String(node.name), "type": cls, "kind": kind})
+	var added := _commit_add(node, parent, root, "Breakpoint: add %s" % node.name)
+	added["type"] = cls
+	added["kind"] = kind
+	return _ok(added)
 
 
 func _camera_create(params: Dictionary) -> Dictionary:
@@ -4318,14 +4367,10 @@ func _camera_create(params: Dictionary) -> Dictionary:
 	node.name = String(params.get("name", "Camera3D"))
 	if bool(params.get("current", false)):
 		node.current = true
-	var ur := _plugin.get_undo_redo()
-	ur.create_action("Breakpoint: add %s" % node.name)
-	ur.add_do_method(parent, "add_child", node)
-	ur.add_do_method(node, "set_owner", root)
-	ur.add_do_reference(node)
-	ur.add_undo_method(parent, "remove_child", node)
-	ur.commit_action()
-	return _ok({"path": _path_of(root, node), "name": String(node.name), "type": "Camera3D", "current": node.current})
+	var added := _commit_add(node, parent, root, "Breakpoint: add %s" % node.name)
+	added["type"] = "Camera3D"
+	added["current"] = node.current
+	return _ok(added)
 
 
 func _environment_create(params: Dictionary) -> Dictionary:
@@ -4340,10 +4385,10 @@ func _environment_create(params: Dictionary) -> Dictionary:
 	env.background_mode = int(modes[bg])
 	if params.has("ambient_color"):
 		env.ambient_light_color = _to_color(params.get("ambient_color"))
-	var e := ResourceSaver.save(env, to_path)
-	if e != OK:
-		return _err("save_failed", "ResourceSaver.save() returned %d" % e)
-	return _ok({"created": to_path, "type": "Environment", "background_mode": bg})
+	var saved := _commit_save(env, to_path, params, SAVE_NEW)
+	if saved.has("error"):
+		return saved["error"]
+	return _ok({"created": to_path, "type": "Environment", "background_mode": bg}.merged(saved["fields"]))
 
 
 func _environment_set_sky(params: Dictionary) -> Dictionary:
@@ -4367,9 +4412,9 @@ func _environment_set_sky(params: Dictionary) -> Dictionary:
 			return _err("bad_params", "Unknown sky_material: %s (procedural/physical/panorama)" % mat_kind)
 	env.sky = sky
 	env.background_mode = Environment.BG_SKY
-	var e := ResourceSaver.save(env, path)
-	if e != OK:
-		return _err("save_failed", "ResourceSaver.save() returned %d" % e)
+	var saved := _commit_save(env, path, params, SAVE_BACK)
+	if saved.has("error"):
+		return saved["error"]
 	return _ok({"path": path, "background_mode": "sky", "sky_material": mat_kind})
 
 
@@ -4389,14 +4434,10 @@ func _csg_create(params: Dictionary) -> Dictionary:
 		return _err("bad_type", "Cannot instantiate class: %s" % cls)
 	var node: Node = ClassDB.instantiate(cls)
 	node.name = String(params.get("name", cls))
-	var ur := _plugin.get_undo_redo()
-	ur.create_action("Breakpoint: add %s" % node.name)
-	ur.add_do_method(parent, "add_child", node)
-	ur.add_do_method(node, "set_owner", root)
-	ur.add_do_reference(node)
-	ur.add_undo_method(parent, "remove_child", node)
-	ur.commit_action()
-	return _ok({"path": _path_of(root, node), "name": String(node.name), "type": cls, "shape": shape})
+	var added := _commit_add(node, parent, root, "Breakpoint: add %s" % node.name)
+	added["type"] = cls
+	added["shape"] = shape
+	return _ok(added)
 
 
 func _navregion_create(params: Dictionary) -> Dictionary:
@@ -4410,14 +4451,10 @@ func _navregion_create(params: Dictionary) -> Dictionary:
 	node.name = String(params.get("name", "NavigationRegion3D"))
 	if bool(params.get("with_navmesh", true)):
 		node.navigation_mesh = NavigationMesh.new()
-	var ur := _plugin.get_undo_redo()
-	ur.create_action("Breakpoint: add %s" % node.name)
-	ur.add_do_method(parent, "add_child", node)
-	ur.add_do_method(node, "set_owner", root)
-	ur.add_do_reference(node)
-	ur.add_undo_method(parent, "remove_child", node)
-	ur.commit_action()
-	return _ok({"path": _path_of(root, node), "name": String(node.name), "type": "NavigationRegion3D", "has_navmesh": node.navigation_mesh != null})
+	var added := _commit_add(node, parent, root, "Breakpoint: add %s" % node.name)
+	added["type"] = "NavigationRegion3D"
+	added["has_navmesh"] = node.navigation_mesh != null
+	return _ok(added)
 
 
 func _navagent_configure(params: Dictionary) -> Dictionary:
@@ -4441,14 +4478,10 @@ func _navagent_configure(params: Dictionary) -> Dictionary:
 		node.target_desired_distance = float(params.get("target_desired_distance"))
 	if params.has("avoidance_enabled"):
 		node.avoidance_enabled = bool(params.get("avoidance_enabled"))
-	var ur := _plugin.get_undo_redo()
-	ur.create_action("Breakpoint: add %s" % node.name)
-	ur.add_do_method(parent, "add_child", node)
-	ur.add_do_method(node, "set_owner", root)
-	ur.add_do_reference(node)
-	ur.add_undo_method(parent, "remove_child", node)
-	ur.commit_action()
-	return _ok({"path": _path_of(root, node), "name": String(node.name), "type": "NavigationAgent3D", "config": {"radius": node.radius, "height": node.height, "max_speed": node.max_speed, "path_desired_distance": node.path_desired_distance, "target_desired_distance": node.target_desired_distance, "avoidance_enabled": node.avoidance_enabled}})
+	var added := _commit_add(node, parent, root, "Breakpoint: add %s" % node.name)
+	added["type"] = "NavigationAgent3D"
+	added["config"] = {"radius": node.radius, "height": node.height, "max_speed": node.max_speed, "path_desired_distance": node.path_desired_distance, "target_desired_distance": node.target_desired_distance, "avoidance_enabled": node.avoidance_enabled}
+	return _ok(added)
 
 
 # ------------------------------------------------ Group I: input/config/testing ----
@@ -4757,20 +4790,11 @@ func _mp_add_spawner(params: Dictionary) -> Dictionary:
 		if sp.begins_with("res://"):
 			spawner.add_spawnable_scene(sp)
 			added_scenes.append(sp)
-	var ur := _plugin.get_undo_redo()
-	ur.create_action("Breakpoint: add %s" % spawner.name)
-	ur.add_do_method(parent, "add_child", spawner)
-	ur.add_do_method(spawner, "set_owner", root)
-	ur.add_do_reference(spawner)
-	ur.add_undo_method(parent, "remove_child", spawner)
-	ur.commit_action()
-	return _ok({
-		"path": _path_of(root, spawner),
-		"name": String(spawner.name),
-		"type": "MultiplayerSpawner",
-		"spawn_path": String(spawner.spawn_path),
-		"spawnable_scenes": added_scenes,
-	})
+	var added := _commit_add(spawner, parent, root, "Breakpoint: add %s" % spawner.name)
+	added["type"] = "MultiplayerSpawner"
+	added["spawn_path"] = String(spawner.spawn_path)
+	added["spawnable_scenes"] = added_scenes
+	return _ok(added)
 
 
 func _mp_add_synchronizer(params: Dictionary) -> Dictionary:
@@ -4801,20 +4825,11 @@ func _mp_add_synchronizer(params: Dictionary) -> Dictionary:
 			cfg.property_set_replication_mode(np, mode)
 			added_props.append(String(p))
 		sync.replication_config = cfg
-	var ur := _plugin.get_undo_redo()
-	ur.create_action("Breakpoint: add %s" % sync.name)
-	ur.add_do_method(parent, "add_child", sync)
-	ur.add_do_method(sync, "set_owner", root)
-	ur.add_do_reference(sync)
-	ur.add_undo_method(parent, "remove_child", sync)
-	ur.commit_action()
-	return _ok({
-		"path": _path_of(root, sync),
-		"name": String(sync.name),
-		"type": "MultiplayerSynchronizer",
-		"root_path": String(sync.root_path),
-		"properties": added_props,
-	})
+	var added := _commit_add(sync, parent, root, "Breakpoint: add %s" % sync.name)
+	added["type"] = "MultiplayerSynchronizer"
+	added["root_path"] = String(sync.root_path)
+	added["properties"] = added_props
+	return _ok(added)
 
 
 func _mp_set_authority(params: Dictionary) -> Dictionary:
@@ -4862,7 +4877,15 @@ func _mp_write_script(params: Dictionary) -> Dictionary:
 	var efs := EditorInterface.get_resource_filesystem()
 	efs.update_file(to_path)
 	efs.scan()
-	return _ok({"status": "written", "path": to_path, "bytes": content.to_utf8_buffer().size(), "created": not existed})
+	# 🆕 284 — `replaced` JOINS `created`, IT DOES NOT REPLACE IT. This reply has carried
+	# `created: false` since the scaffold family was built, which is a fifth spelling of
+	# the one question 284 unified — and callers branch on it, so it stays. What is added
+	# is the field every other destination-writing tool now answers with, present only
+	# when it happened, so one convention covers the whole surface.
+	var out := {"status": "written", "path": to_path, "bytes": content.to_utf8_buffer().size(), "created": not existed}
+	if existed:
+		out["replaced"] = true
+	return _ok(out)
 
 
 ## Detect which known game-backend SDKs are installed in this project. Each is