gdharness 1.3.68 → 1.3.70

package/build/cli.js

@@ -21188,7 +21188,7 @@ var init_tool_definitions = __esm(() => {
       name: "scene_tree",
       title: "Scene tree",
       effect: "read",
-      description: "The nodes of a scene file: names, classes and hierarchy, with properties when asked. type is the engine class, and a node whose script declares a class_name names it under scriptClass, as scene_node get does. A node that instances another scene names that file under instanceOf, and the nodes listed under it come from that file rather than this one. Its editableChildren says whether this scene, or a scene it inherits, keeps values of its own for them (scene_node set editableChildren). The root of a scene inheriting another names the scene it inherits under inherits, and every node that scene or one further down makes names its file under inheritedFrom. This file holds only the values it changes on them. A node in any group answers groups, sorted, from this file and every scene it comes from. Needs no editor: one serving the project answers and says whether it holds unsaved changes to the scene, and with none a headless engine reads the file without making its nodes, so no script of theirs runs (autoloads still start once it has answered, as in every headless call). For the nodes of a game that is running, runtime_inspect tree.",
+      description: "The nodes of a scene file: names, classes and hierarchy, with properties when asked. type is the engine class, and a node whose script declares a class_name names it under scriptClass, as scene_node get does. A node that instances another scene names that file under instanceOf, and the nodes listed under it come from that file rather than this one. Its editableChildren says whether this scene, or a scene it inherits, keeps values of its own for them (scene_node set editableChildren). One saved as a placeholder answers placeholder true, with InstancePlaceholder as its type, as a game loads it (scene_node set placeholder). The root of a scene inheriting another names the scene it inherits under inherits, and every node that scene or one further down makes names its file under inheritedFrom. This file holds only the values it changes on them. A node in any group answers groups, sorted, from this file and every scene it comes from. Needs no editor: one serving the project answers and says whether it holds unsaved changes to the scene, and with none a headless engine reads the file without making its nodes, so no script of theirs runs (autoloads still start once it has answered, as in every headless call). For the nodes of a game that is running, runtime_inspect tree.",
       parameters: {
         projectPath: PROJECT_PATH,
         scenePath: SCENE_PATH,
@@ -21256,6 +21256,11 @@ var init_tool_definitions = __esm(() => {
           ops: ["set"],
           description: "set: on an instance of another scene, whether its children are editable here, as the editor's Editable Children makes them. True lets scene_node set give the nodes inside that instance values of this scene's own, which no other instance shares. An instance nested inside another takes it once the one around it has editable children. False drops every value this scene keeps for them, and every node it added below one of them. The answer names the nodes whose values went under droppedValues (they stay, with the instance's own values) and the added nodes that went under droppedNodes. A node added straight under the instance stays. The answer says editableChildren as the file now holds it."
         },
+        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. 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",
           items: { type: "string" },
@@ -21310,12 +21315,12 @@ var init_tool_definitions = __esm(() => {
         },
         get: {
           effect: "read",
-          summary: "read a node's class, path, properties and where its values come from, and a TileMapLayer's or TileMap's cells as set_tilemap_cells takes them, the first 1000 with cellCount for all. An instance of another scene also answers instanceOf and editableChildren, as scene_tree does",
+          summary: "read a node's class, path, properties and where its values come from, and a TileMapLayer's or TileMap's cells as set_tilemap_cells takes them, the first 1000 with cellCount for all. An instance of another scene also answers instanceOf, editableChildren and placeholder",
           requires: ["nodePath"]
         },
         set: {
           effect: "destructive",
-          summary: "set properties on a node, make the children of an instance editable, or put it in groups or take it out of them, or any of them together",
+          summary: "set properties on a node, make the children of an instance editable or the instance a placeholder, or put it in groups or take it out of them, or any of them together",
           requires: ["nodePath"]
         },
         duplicate: {
@@ -21972,7 +21977,7 @@ var init_tool_definitions = __esm(() => {
         },
         wait: {
           effect: "read",
-          summary: "wait for the run to end, or to be held by its debugger at a breakpoint, a pause or a step, then answer as editor_output does",
+          summary: "wait for the run to end, to be held by its debugger at a breakpoint, a pause or a step, or to have crashed, then answer as editor_output does",
           requires: []
         },
         profile: {
@@ -59398,6 +59403,8 @@ ${error.text}`;
     const cancelled = callSignal();
     let held = false;
     let holdAsked = 0;
+    let crashedAt;
+    let crashed = false;
     while (cancelled?.aborted !== true && await this.runStillGoing(run) && Date.now() < until) {
       this.drainEditorOutput(run);
       this.drainTranscript(run);
@@ -59407,13 +59414,19 @@ ${error.text}`;
           held = true;
           break;
         }
+        crashedAt ??= run.log.crashReport() === undefined ? undefined : Date.now();
+      }
+      if (crashedAt !== undefined && Date.now() - crashedAt >= CRASH_EXIT_GRACE_MS) {
+        crashed = true;
+        break;
       }
       await delay10(RUN_POLL_MS);
     }
     if (!await this.runStillGoing(run)) {
       return await this.handleGetDebugOutput(args);
     }
-    return await this.handleGetDebugOutput(args, held ? { heldAfterMs: Date.now() - began } : { ranOutMs: budgetMs });
+    const after = Date.now() - began;
+    return await this.handleGetDebugOutput(args, held ? { heldAfterMs: after } : crashed ? { crashedAfterMs: after } : { ranOutMs: budgetMs });
   }
   async heldByItsDebugger(run) {
     if (!run.throughEditor) {
@@ -59611,6 +59624,9 @@ ${error.text}`;
     if (waited !== undefined && "heldAfterMs" in waited) {
       notes.push(`The wait answered after ${waited.heldAfterMs}ms because the game is held by its debugger, where heldAt says, and a held game does not end: debug_control continue lets it go, and editor_run wait then waits on.`);
     }
+    if (waited !== undefined && "crashedAfterMs" in waited) {
+      notes.push(`The wait answered after ${waited.crashedAfterMs}ms because the game crashed and printed its crash report, under entries. Its process has not ended yet, since the system can hold a crashed process while it reports the crash, as Windows Error Reporting does. Nothing more will come from the game. editor_run stop ends it now.`);
+    }
     const restarts = run.restartedFrom ?? [];
     if (restarts.length > 0) {
       const chain = [...restarts.map((one) => one.pid), run.pid].join(" into ");
@@ -61552,7 +61568,7 @@ async function runGodotServer() {
   const server = new GodotServer;
   await server.run();
 }
-var TYPE_ARGUMENTS, UPDATE_NOTICE_EVERY = 500, FEEDBACK_NOTICE_EVERY = 250, FAILED_BUDGET = 1e6, ANSWER_BUDGET = 4000000, __dirname2, PARENT_ASKED_AFTER_MS = 5000, EDITOR_SERVERS_START_MS = 20000, HOLD_PING_MS = 2000, HIDDEN_WITH_SOUND = "A hidden editor plays no sound, so silent: false is refused with it.", HIDDEN_WITH_SOUND_FIX = "Pass hidden: false to hear the editor, or leave silent out", SLOWEST_FRAME_RATE = 20, ALONGSIDE_NOTE = "Another call on this game was running while this one was: calls sent together run together and are answered as each finishes, so this answer is not from after the other. Send a call meant to come after another once that one has answered.", OWN_DEBUGGER = " Its debugger is the keeper holding it rather than the editor, so the debug_* tools answer for it all the same: breakpoints stop it, and debug_control pause breaks into it wherever it is, which the editor offers no way to do.", PLAY_STARTS_WITHIN_MS = 30000, KEEPER_ANSWER_MS = 15000, KEEPER_DEBUG_MS, EXIT_REPORTED_WITHIN_MS = 2000, SUCCESSOR_SOUGHT_WITHIN_MS = 20000, CLOSE_ASK_MS = 3000, LONGEST_BOOT_NOTED_MS, PROFILE_SEND_MS = 5000, MOST_GROUPS = 20, RUNTIME_LISTENING_LINE = "[gdharness] runtime listening on ", VALUE_NAMES, BRIDGE_RETRY_MS = 2000, SUCCESSOR_CHECK_MS = 1e4, CONSOLE_WATCH_MS = 250, BOUNDARY_WAIT_MS = 2000, HANDOVER_MS, HANDOVER_POLL_MS = 250, CACHE_WRITE_MS = 2000, STREAMS_GRACE_MS = 2000, PLAYING_STATUS_MS = 1000, SCAN_SETTLED_MS = 500, SLOW_ANSWER_MS = 1000, REIMPORT_TIMEOUT_MS = 300000, OPS_ELSEWHERE, AUDIO_BUS_OPS, STALLED_AFTER_MS = 30000, TEST_TIMEOUT_MS = 600000, TEST_HEARTBEAT_MS = 20000, DEPENDED_FAILED = "Failed to compile depended scripts", LOOPING_AFTER = 100, WAIT_FOR_RUN_MS = 600000, RUN_POLL_MS = 250, HOLD_ASKED_EVERY_MS = 1000, PATH_SOLUTIONS, DESTINATION_ARGUMENTS, OUTPUT_PATH_SOLUTIONS, PROJECT_FILE_ARGUMENTS, DEBUG_STATE_CALLS, PROJECT_INFO_SECTIONS2, RUNNER_DIRECTORY = "addons/gdUnit4/", PROFILE_FUNCTIONS = 30, PROFILER_ON_MS = 3000, PROPERTY_PLACES = "It is a property, so each place says whether it writes it (access write), which runs its set block, or reads it (access read), which runs its get block: withinCalls on a read says nothing of the set block, nor on a write of the get block unless the write is a compound one such as +=. Inside the property's own blocks its name is the value stored, which the engine reads and writes without running them, so those lines are not listed.", CALLERS_FOUND_BY_NAME = "Found by name in the project's scripts, since the engine's profiler counts calls and time per function and records nothing about who made them: a method of the same name on another class is listed too, unless one class was asked about and it is called through another class by name or through a variable declared as one. Each place carries the profile's numbers for the function it is written in.", MOST_ENGINE_ENTRIES = 200, MOST_PRINTED_LINES = 50, MOST_UNDECLARED_ERRORS = 20, ERROR_ASSERT = "GdUnitGodotErrorAssertImpl.gd", RAISED_WARNING = " (Warning treated as error.)", PARSE_ERROR2 = "Parse Error: ", EXTERNAL_MEMBER = 'Could not resolve external class member "', STATIC_LIST_HINT;
+var TYPE_ARGUMENTS, UPDATE_NOTICE_EVERY = 500, FEEDBACK_NOTICE_EVERY = 250, FAILED_BUDGET = 1e6, ANSWER_BUDGET = 4000000, __dirname2, PARENT_ASKED_AFTER_MS = 5000, EDITOR_SERVERS_START_MS = 20000, HOLD_PING_MS = 2000, HIDDEN_WITH_SOUND = "A hidden editor plays no sound, so silent: false is refused with it.", HIDDEN_WITH_SOUND_FIX = "Pass hidden: false to hear the editor, or leave silent out", SLOWEST_FRAME_RATE = 20, ALONGSIDE_NOTE = "Another call on this game was running while this one was: calls sent together run together and are answered as each finishes, so this answer is not from after the other. Send a call meant to come after another once that one has answered.", OWN_DEBUGGER = " Its debugger is the keeper holding it rather than the editor, so the debug_* tools answer for it all the same: breakpoints stop it, and debug_control pause breaks into it wherever it is, which the editor offers no way to do.", PLAY_STARTS_WITHIN_MS = 30000, KEEPER_ANSWER_MS = 15000, KEEPER_DEBUG_MS, EXIT_REPORTED_WITHIN_MS = 2000, SUCCESSOR_SOUGHT_WITHIN_MS = 20000, CLOSE_ASK_MS = 3000, LONGEST_BOOT_NOTED_MS, PROFILE_SEND_MS = 5000, MOST_GROUPS = 20, RUNTIME_LISTENING_LINE = "[gdharness] runtime listening on ", VALUE_NAMES, BRIDGE_RETRY_MS = 2000, SUCCESSOR_CHECK_MS = 1e4, CONSOLE_WATCH_MS = 250, BOUNDARY_WAIT_MS = 2000, HANDOVER_MS, HANDOVER_POLL_MS = 250, CACHE_WRITE_MS = 2000, STREAMS_GRACE_MS = 2000, PLAYING_STATUS_MS = 1000, SCAN_SETTLED_MS = 500, SLOW_ANSWER_MS = 1000, REIMPORT_TIMEOUT_MS = 300000, OPS_ELSEWHERE, AUDIO_BUS_OPS, STALLED_AFTER_MS = 30000, TEST_TIMEOUT_MS = 600000, TEST_HEARTBEAT_MS = 20000, DEPENDED_FAILED = "Failed to compile depended scripts", LOOPING_AFTER = 100, WAIT_FOR_RUN_MS = 600000, RUN_POLL_MS = 250, HOLD_ASKED_EVERY_MS = 1000, CRASH_EXIT_GRACE_MS = 1e4, PATH_SOLUTIONS, DESTINATION_ARGUMENTS, OUTPUT_PATH_SOLUTIONS, PROJECT_FILE_ARGUMENTS, DEBUG_STATE_CALLS, PROJECT_INFO_SECTIONS2, RUNNER_DIRECTORY = "addons/gdUnit4/", PROFILE_FUNCTIONS = 30, PROFILER_ON_MS = 3000, PROPERTY_PLACES = "It is a property, so each place says whether it writes it (access write), which runs its set block, or reads it (access read), which runs its get block: withinCalls on a read says nothing of the set block, nor on a write of the get block unless the write is a compound one such as +=. Inside the property's own blocks its name is the value stored, which the engine reads and writes without running them, so those lines are not listed.", CALLERS_FOUND_BY_NAME = "Found by name in the project's scripts, since the engine's profiler counts calls and time per function and records nothing about who made them: a method of the same name on another class is listed too, unless one class was asked about and it is called through another class by name or through a variable declared as one. Each place carries the profile's numbers for the function it is written in.", MOST_ENGINE_ENTRIES = 200, MOST_PRINTED_LINES = 50, MOST_UNDECLARED_ERRORS = 20, ERROR_ASSERT = "GdUnitGodotErrorAssertImpl.gd", RAISED_WARNING = " (Warning treated as error.)", PARSE_ERROR2 = "Parse Error: ", EXTERNAL_MEMBER = 'Could not resolve external class member "', STATIC_LIST_HINT;
 var init_server = __esm(() => {
   init_dist2();
   init_stdio();

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

@@ -186,6 +186,7 @@ static func _lay(
 			elif state.is_node_instance_placeholder(index):
 				nodes[path] = _made("InstancePlaceholder")
 				nodes[path]["instanceOf"] = state.get_node_instance_placeholder(index)
+				nodes[path]["placeholder"] = true
 			elif str(state.get_node_type(index)).is_empty():
 				# An entry for a node of an instance that no longer has it, which the engine skips
 				# too.
@@ -367,6 +368,8 @@ static func _entry(
 		data["instanceOf"] = node["instanceOf"]
 		if node.has("editableChildren"):
 			data["editableChildren"] = node["editableChildren"]
+		if node.has("placeholder"):
+			data["placeholder"] = true
 	# An inherited scene's file holds only what it changes, so the read says what it inherits and
 	# which nodes come from there, as the editor greys them.
 	if node.has("inherits"):

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.
@@ -124,6 +128,8 @@ func open(scene_path: String, for_writing: bool) -> Dictionary:
 		return { "ok": false, "error": "Failed to load %s as a scene" % path }
 	if root == null:
 		return { "ok": false, "error": "Failed to instantiate " + path }
+	if not Engine.is_editor_hint():
+		_unhold_placeholders()
 	_state = packed.get_state()
 	_base_paths = makers(_state)
 	if for_writing:
@@ -145,6 +151,133 @@ func open(scene_path: String, for_writing: bool) -> Dictionary:
 	return {}
 
 
+## Puts back each placeholder this scene places as the instance itself, marked, as an editor opens
+## it. An engine with no editor opens one as an InstancePlaceholder even in an edit state, and the
+## scene then packs it as a node of that class with every value it holds, so a save lost the mark.
+## The instance takes the placeholder's place, values, groups, connections and the node values
+## naming it. One whose scene does not instance stays as it was.
+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
+		)
+		var instance: Node = (
+			packed.instantiate(PackedScene.GEN_EDIT_STATE_INSTANCE) if packed != null else null
+		)
+		if instance == null:
+			continue
+		instance.name = one.name
+		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():
+		if child is InstancePlaceholder and child.owner == root:
+			into.append(child as InstancePlaceholder)
+		else:
+			_placeholders_under(child, into)
+
+
+## Points every value of a node of this scene that holds [param was], alone or in an array, at
+## [param now].
+func _repointed(top: Node, was: Node, now: Node) -> void:
+	if top.owner == root or top == root:
+		for declared: Dictionary in top.get_property_list():
+			if not GdhRead.as_int(declared.get("usage", 0)) & PROPERTY_USAGE_STORAGE:
+				continue
+			var named: String = str(declared["name"])
+			var value: Variant = top.get(named)
+			if value is Object and value == was:
+				top.set(named, now)
+			elif value is Array:
+				var listed: Array = value
+				if listed.has(was):
+					var swapped: Array = listed.duplicate()
+					for index: int in swapped.size():
+						if swapped[index] == was:
+							swapped[index] = now
+					top.set(named, swapped)
+	for child: Node in top.get_children():
+		_repointed(child, was, now)
+
+
 ## Why a write to the scene at [param scene_path], whose text is [param text], is refused, or "":
 ## an [ext_resource] naming no file the project has, by its uid or by its path. The engine loads the
 ## scene without it, so a save drops the entry and every value set from it, and the answer could
@@ -1013,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):
@@ -1024,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/scene_tools.gd

@@ -263,9 +263,15 @@ func add_node(args: Dictionary) -> Dictionary:
 	var parent_node_path: String = str(args.get("parentNodePath", "."))
 	var properties: Dictionary = _parse_properties_arg(args.get("properties", {}))
 	var adding: Array = GdhGroups.asked(args, "addGroups")
+	var placeholder: bool = GdhRead.as_bool(args.get("placeholder", false))
 
 	if node_name.is_empty():
 		return { "ok": false, "error": "Missing nodeName" }
+	if placeholder and instance_path.is_empty():
+		return {
+			"ok": false,
+			"error": "placeholder marks an instance of a scene, so add takes it with instancePath.",
+		}
 	var class_script: Script = null
 	if not node_type.is_empty() and not ClassDB.class_exists(node_type):
 		var declared: Dictionary = GdhSceneFile.script_class(node_type, "Node")
@@ -312,6 +318,8 @@ func add_node(args: Dictionary) -> Dictionary:
 	parent.add_child(new_node)
 	GdhPlacing.place(new_node, place)
 	GdhPlacing.own(new_node, root)
+	if placeholder:
+		new_node.set_scene_instance_load_placeholder(true)
 	if class_script != null:
 		scene.asked(new_node, ["script"])
 		new_node.set_script(class_script)
@@ -357,6 +365,8 @@ func add_node(args: Dictionary) -> Dictionary:
 			)
 			if unkept.is_empty() and saved.get_node_or_null(new_path) != null:
 				unkept = GdhGroups.unkept(saved.get_node(new_path), adding, [])
+			if unkept.is_empty() and placeholder:
+				unkept = _placeholder_unkept(saved, new_path, true)
 			return unkept
 	)
 	if not written.is_empty():
@@ -366,9 +376,25 @@ func add_node(args: Dictionary) -> Dictionary:
 	_note_loads_as(answer, scene, new_path)
 	if packed != null:
 		answer["instanceOf"] = instance_path
+		answer["placeholder"] = placeholder
 	return answer
 
 
+## Why the node at [param at] in [param saved], the scene as written, would not load with
+## placeholder [param wanted], or "" when it would.
+static func _placeholder_unkept(saved: Node, at: String, wanted: bool) -> String:
+	var node: Node = saved.get_node_or_null(at)
+	if node == null or _placeholder_of(node) == wanted:
+		return ""
+	return "%s would load with placeholder %s." % [at, not wanted]
+
+
+## Whether [param node] is an instance saved as a placeholder. An engine with no editor opens one as
+## an InstancePlaceholder even in an edit state, and an editor opens the instance itself, marked.
+static func _placeholder_of(node: Node) -> bool:
+	return node is InstancePlaceholder or node.get_scene_instance_load_placeholder()
+
+
 func delete_node(args: Dictionary) -> Dictionary:
 	var project_path: String = str(args.get("projectPath", ""))
 	var scene_path: String = GdhSceneFile.res_path(project_path, str(args.get("scenePath", "")))
@@ -1119,10 +1145,18 @@ func set_node_properties(args: Dictionary) -> Dictionary:
 	var editable: Variant = args.get("editableChildren")
 	var adding: Array = GdhGroups.asked(args, "addGroups")
 	var removing: Array = GdhGroups.asked(args, "removeGroups")
-	if properties.is_empty() and editable == null and adding.is_empty() and removing.is_empty():
+	var placeholder: Variant = args.get("placeholder")
+	if (
+		properties.is_empty()
+		and editable == null
+		and placeholder == null
+		and adding.is_empty()
+		and removing.is_empty()
+	):
 		return {
 			"ok": false,
-			"error": "set takes properties, editableChildren, addGroups or removeGroups.",
+			"error":
+			"set takes properties, editableChildren, placeholder, addGroups or removeGroups.",
 		}
 
 	var opened: Array = _open(scene_path, true)
@@ -1147,6 +1181,37 @@ 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."
+			)
+		)
+	if wants_placeholder and editable == null and scene.root.is_editable_instance(node):
+		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))
@@ -1154,6 +1219,16 @@ func set_node_properties(args: Dictionary) -> Dictionary:
 			return scene.refuse(not_an_instance)
 		if not GdhRead.as_bool(editable):
 			dropped = scene.held_under(scene.path_of(node))
+	if placeholder != null:
+		# The editor offers Load as Placeholder only on an instance this scene places itself.
+		if node == scene.root or node.owner != scene.root or node.scene_file_path.is_empty():
+			return scene.refuse(
+				(
+					"placeholder is a setting of an instance this scene places, and %s is not one."
+					% scene.path_of(node)
+				)
+			)
+		node.set_scene_instance_load_placeholder(GdhRead.as_bool(placeholder))
 
 	var old_path: String = scene.path_of(node)
 	scene.asked(node, properties.keys())
@@ -1219,6 +1294,8 @@ func set_node_properties(args: Dictionary) -> Dictionary:
 						"%s would load with editableChildren %s."
 						% [new_path, not GdhRead.as_bool(editable)]
 					)
+			if unkept.is_empty() and placeholder != null:
+				unkept = _placeholder_unkept(saved, new_path, GdhRead.as_bool(placeholder))
 			return unkept
 	)
 	if not written.is_empty():
@@ -1227,6 +1304,8 @@ func set_node_properties(args: Dictionary) -> Dictionary:
 
 	if editable != null:
 		answer["editableChildren"] = GdhRead.as_bool(editable)
+	if placeholder != null:
+		answer["placeholder"] = GdhRead.as_bool(placeholder)
 	if not dropped.is_empty():
 		answer["droppedValues"] = dropped["values"]
 		answer["droppedNodes"] = dropped["nodes"]
@@ -1404,6 +1483,7 @@ func get_node_properties(args: Dictionary) -> Dictionary:
 	if node != scene.root and node.owner != null and not node.scene_file_path.is_empty():
 		answer["instanceOf"] = node.scene_file_path
 		answer["editableChildren"] = scene.root.is_editable_instance(node)
+		answer["placeholder"] = node.get_scene_instance_load_placeholder()
 	scene.close()
 	# Only an editor holds anything unsaved. A headless engine answering false would say it looked.
 	if Engine.is_editor_hint():

package/build/godot/operations/file_reads.gd

@@ -186,6 +186,7 @@ static func _lay(
 			elif state.is_node_instance_placeholder(index):
 				nodes[path] = _made("InstancePlaceholder")
 				nodes[path]["instanceOf"] = state.get_node_instance_placeholder(index)
+				nodes[path]["placeholder"] = true
 			elif str(state.get_node_type(index)).is_empty():
 				# An entry for a node of an instance that no longer has it, which the engine skips
 				# too.
@@ -367,6 +368,8 @@ static func _entry(
 		data["instanceOf"] = node["instanceOf"]
 		if node.has("editableChildren"):
 			data["editableChildren"] = node["editableChildren"]
+		if node.has("placeholder"):
+			data["placeholder"] = true
 	# An inherited scene's file holds only what it changes, so the read says what it inherits and
 	# which nodes come from there, as the editor greys them.
 	if node.has("inherits"):

package/package.json

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