gdharness 1.3.2 → 1.3.3

package/build/cli.js

@@ -12095,7 +12095,7 @@ var init_tool_definitions = __esm(() => {
     {
       name: "project_settings",
       title: "Project settings",
-      description: "Reads or writes project.godot: settings, autoloads, the main scene, input actions, plugins and audio buses. A write with an editor open on the project is handed to the editor, which takes the settings the write changed or names from the file (named under editorAdopted), including a setting the file already held, since the editor can hold another value after the file was put back, or reloads the bus layout, so it answers the new values and does not save the old ones back over them. editorNote is an editor that could not take the write, or one on another release's addon that was not asked, which still holds the old values until editor_launch restart. An enabled plugin's code still loads on the editor's next start. set answers old_value and new_value, with was_new true when project.godot did not set the setting before, and was_default true when what it held was the engine's own default, which old_value then is. add_input_action on an action that exists, one of the engine's ui_ actions included, replaces its events and deadzone, and answers was_new false with what it held under old_events and old_deadzone. A set of the value the setting already holds, in the same type, writes nothing and answers unchanged true and saved false. Every write keeps the sections and keys of project.godot in the order the file had them, so a change moves no other line; the save is the engine's, and like the editor's it writes Godot's header and config/features into a file that lacks them. get answers exists, true for any setting the engine knows, and at_default, true when the value is the engine's own default and so has no line in project.godot. Each setting under prefix carries at_default too, so a family read separates what the project sets from the engine's defaults; it is absent for a setting the engine registers no default for, such as an input action the project added, which only the project can have set.",
+      description: "Reads or writes project.godot: settings, autoloads, the main scene, input actions, plugins and audio buses. project_info include lists the autoloads, input actions and audio buses as the project holds them. A write with an editor open on the project is handed to the editor, which takes the settings the write changed or names from the file (named under editorAdopted), including a setting the file already held, since the editor can hold another value after the file was put back, or reloads the bus layout, so it answers the new values and does not save the old ones back over them. editorNote is an editor that could not take the write, or one on another release's addon that was not asked, which still holds the old values until editor_launch restart. An enabled plugin's code still loads on the editor's next start. set answers old_value and new_value, with was_new true when project.godot did not set the setting before, and was_default true when what it held was the engine's own default, which old_value then is. add_input_action on an action that exists, one of the engine's ui_ actions included, replaces its events and deadzone, and answers was_new false with what it held under old_events and old_deadzone. A set of the value the setting already holds, in the same type, writes nothing and answers unchanged true and saved false. Every write keeps the sections and keys of project.godot in the order the file had them, so a change moves no other line; the save is the engine's, and like the editor's it writes Godot's header and config/features into a file that lacks them. get answers exists, true for any setting the engine knows, and at_default, true when the value is the engine's own default and so has no line in project.godot. Each setting under prefix carries at_default too, so a family read separates what the project sets from the engine's defaults; it is absent for a setting the engine registers no default for, such as an input action the project added, which only the project can have set.",
       parameters: {
         projectPath: PROJECT_PATH,
         setting: {
@@ -12317,7 +12317,7 @@ var init_tool_definitions = __esm(() => {
         },
         reimport: {
           effect: "destructive",
-          summary: "reimport what status says is outdated or failed, one resource with resourcePath, or what is current as well with force. Through the open editor when one serves the project, so it reloads what it holds, waiting for it to finish; otherwise through the engine's own import pass. The editor scans first, since its reimport passes over a file it has not taken in, such as one an installer has just written; what that scan imported is named under importedByTheScan and is not imported again unless force asks. Answered from a second status read: reimported lists what is current now, notReimported what is not, one entry per status and reason with the paths sharing them, and via says which of the two did the work. When nothing needs reimporting, nothing runs, and the answer has the two lists empty, a note saying so, and no via. A whole-project reimport also answers missingSource, the .import files whose source is not beside them, empty when there are none, whether or not anything needed reimporting; one resourcePath is not a walk of the project and leaves it out. stillImporting is an editor that had not finished within timeoutMs",
+          summary: "reimport what status says is outdated or failed, one resource with resourcePath, or what is current as well with force. Through the open editor when one serves the project, so it reloads what it holds, waiting for it to finish; otherwise through the engine's own import pass. The editor scans first, since its reimport passes over a file it has not taken in, such as one an installer has just written; what that scan imported is named under importedByTheScan and is not imported again unless force asks. Answered from a second status read: reimported lists what is current now, notReimported what is not, one entry per status and reason with the paths sharing them, and via says which of the two did the work. Either takes in every file that is behind, so a reimport of one resourcePath names under alsoImported the others it imported. When nothing needs reimporting, nothing runs, and the answer has the two lists empty, a note saying so, and no via. A whole-project reimport also answers missingSource, the .import files whose source is not beside them, empty when there are none, whether or not anything needed reimporting; one resourcePath is not a walk of the project and leaves it out. stillImporting is an editor that had not finished within timeoutMs",
           requires: []
         },
         uid: {
@@ -12419,7 +12419,7 @@ var init_tool_definitions = __esm(() => {
     {
       name: "scene_create",
       title: "Create or save a scene",
-      description: `Creates a scene file where none is, saves one, or saves a copy under a new path. A save of a scene open in the editor saves the editor's copy, unsaved changes included. ${WITHOUT_AN_EDITOR}`,
+      description: `Creates a scene file where none is, saves one, or saves a copy under a new path. create makes a folder the path names that is not there, and names it under madeFolder. A save of a scene open in the editor saves the editor's copy, unsaved changes included. ${WITHOUT_AN_EDITOR}`,
       parameters: {
         projectPath: PROJECT_PATH,
         scenePath: SCENE_PATH,
@@ -12606,31 +12606,40 @@ var init_tool_definitions = __esm(() => {
     {
       name: "scene_animation",
       title: "Animations",
-      description: "Animations in an AnimationPlayer and states in an AnimationTree state machine. read answers with every track of an animation in the shape add_track takes, so a track read off one animation can be added to another. read and read_states need 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 running the scene's scripts. The ops that write go through the editor when one serves the project; with none, a headless engine runs the editor's own tool and the answer says so under writtenBy. That engine runs every script of the file, where the editor runs only tool scripts, so what a script changes as the file loads is put back before anything is saved, and a file where that cannot be done, such as a scene whose script does not compile, is refused and nothing is written. An editor of the project that is running and has not reached this server is waited for rather than written around.",
+      description: "Animations in an AnimationPlayer and states in an AnimationTree state machine. read answers with every track of an animation in the shape add_track takes, so a track read off one animation can be added to another. add_track on a path the animation already has a track of that type for adds the keys to that track, as the editor keys a property it already animates, answering existingTrack true and keysAdded beside keys, the track's count; a key at a time that track already has a key at is refused. A key past the animation's end, where it never plays, is written and named under pastLength. remove clears the player's autoplay when it named the animation and names under statesPlayingNothing the states that played it. read and read_states need 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 running the scene's scripts. The ops that write go through the editor when one serves the project; with none, a headless engine runs the editor's own tool and the answer says so under writtenBy. That engine runs every script of the file, where the editor runs only tool scripts, so what a script changes as the file loads is put back before anything is saved, and a file where that cannot be done, such as a scene whose script does not compile, is refused and nothing is written. An editor of the project that is running and has not reached this server is waited for rather than written around.",
       parameters: {
         projectPath: PROJECT_PATH,
         scenePath: SCENE_PATH,
         playerNodePath: {
           type: "string",
-          ops: ["read", "create", "add_track"],
+          ops: ["read", "create", "add_track", "set", "rename", "remove"],
           description: "The AnimationPlayer node."
         },
         animationName: {
           type: "string",
-          ops: ["read", "create", "add_track", "add_state"],
+          ops: ["read", "create", "add_track", "set", "rename", "remove", "add_state"],
           description: "The animation in the player. read: the one to answer with whole, its tracks a list; without it, read lists them, each with the number of its tracks under tracks. add_state: the one that state plays."
         },
-        length: { type: "number", ops: ["create"], description: "create: seconds. Default 1." },
+        newName: {
+          type: "string",
+          ops: ["rename"],
+          description: "rename: the animation's new name in the library it is in. The player's autoplay and every state of the scene's AnimationTrees that plays it are renamed with it, named under autoplay and statesFollowed."
+        },
+        length: {
+          type: "number",
+          ops: ["create", "set"],
+          description: "create and set: seconds, more than 0. create: default 1. set: a key past the new end is kept, as the editor keeps it, and named under pastLength, since it never plays."
+        },
         loopMode: {
           type: "string",
-          ops: ["create"],
+          ops: ["create", "set"],
           enum: ["none", "linear", "pingpong"],
           description: "create: default none."
         },
         step: {
           type: "number",
-          ops: ["create"],
-          description: "create: keyframe snap in seconds. Default 0.1."
+          ops: ["create", "set"],
+          description: "create and set: keyframe snap in seconds, 0 or more. create: default 0.1."
         },
         track: { ...ANIMATION_TRACK, ops: ["add_track"] },
         animTreePath: {
@@ -12692,6 +12701,21 @@ var init_tool_definitions = __esm(() => {
           summary: "a property or method track with keyframes",
           requires: ["playerNodePath", "animationName", "track"]
         },
+        set: {
+          effect: "destructive",
+          summary: "an animation's length, loop mode or step",
+          requires: ["playerNodePath", "animationName"]
+        },
+        rename: {
+          effect: "destructive",
+          summary: "an animation, with what plays it",
+          requires: ["playerNodePath", "animationName", "newName"]
+        },
+        remove: {
+          effect: "destructive",
+          summary: "an animation from its player",
+          requires: ["playerNodePath", "animationName"]
+        },
         add_state: {
           effect: "additive",
           summary: "a state playing an animation, in an AnimationTree",
@@ -12868,7 +12892,7 @@ var init_tool_definitions = __esm(() => {
         preview: {
           type: "boolean",
           ops: ["move"],
-          description: "move: answer with what would move and change, and write nothing. Default false."
+          description: "move: answer with what would move and change, and write nothing. A move that would be refused is refused here too, with the same reason. Default false."
         },
         controlType: {
           type: "string",
@@ -47291,6 +47315,12 @@ class GodotServer {
             return await editorOrEngine("create_animation", "writes");
           case "add_track":
             return await editorOrEngine("add_animation_track", "writes");
+          case "set":
+            return await editorOrEngine("set_animation", "writes");
+          case "rename":
+            return await editorOrEngine("rename_animation", "writes");
+          case "remove":
+            return await editorOrEngine("remove_animation", "writes");
           case "add_state":
             return await editorOrEngine("add_animation_state", "writes");
           default:
@@ -48088,6 +48118,13 @@ class GodotServer {
     const viaEditor = this.editorHasOpen(projectPath);
     const extra = {};
     const statusAsk = resourcePath === undefined ? { includeUpToDate: true } : { resourcePath };
+    let behindElsewhere = [];
+    if (resourcePath !== undefined) {
+      const whole = await this.operation("get_import_status", {}, projectPath);
+      if (whole.ok) {
+        behindElsewhere = importStatuses(whole.payload).filter((one) => one.status !== "up_to_date" && one.status !== "missing_source" && one.status !== "not_imported" && !targets.includes(one.path)).map((one) => one.path);
+      }
+    }
     if (viaEditor) {
       const scan = await this.handleRescanFilesystem({ projectPath, timeoutMs });
       if (scan.isError === true) {
@@ -48169,6 +48206,16 @@ class GodotServer {
       groups.set(key, group);
     }
     const notReimported = [...groups.values()];
+    if (behindElsewhere.length > 0) {
+      const whole = await this.operation("get_import_status", { includeUpToDate: true }, projectPath);
+      if (whole.ok) {
+        const current = new Set(importStatuses(whole.payload).filter((one) => one.status === "up_to_date").map((one) => one.path));
+        const alsoImported = behindElsewhere.filter((path) => current.has(path));
+        if (alsoImported.length > 0) {
+          extra["alsoImported"] = alsoImported;
+        }
+      }
+    }
     return {
       ok: true,
       payload: {

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

@@ -81,15 +81,7 @@ static func animations(player: AnimationPlayer, animation_name: String) -> Dicti
 			listed.append(summary)
 		return {"ok": true, "animations": listed}
 	if not player.has_animation(StringName(animation_name)):
-		var names: PackedStringArray = player.get_animation_list()
-		return {
-			"ok": false,
-			"error":
-			(
-				"%s has no animation %s. It has: %s."
-				% [player.name, animation_name, ", ".join(names) if not names.is_empty() else "none"]
-			)
-		}
+		return {"ok": false, "error": no_animation(player, str(player.name), animation_name)}
 	var anim: Animation = player.get_animation(StringName(animation_name))
 	var answer: Dictionary = _summary(anim)
 	answer["ok"] = true
@@ -102,6 +94,16 @@ static func animations(player: AnimationPlayer, animation_name: String) -> Dicti
 	return answer
 
 
+## Why [param player], called [param called], cannot be asked for [param animation_name], with the
+## animations it has.
+static func no_animation(player: AnimationPlayer, called: String, animation_name: String) -> String:
+	var names: PackedStringArray = player.get_animation_list()
+	return (
+		"%s has no animation %s. It has: %s."
+		% [called, animation_name, ", ".join(names) if not names.is_empty() else "none"]
+	)
+
+
 static func _summary(anim: Animation) -> Dictionary:
 	return {
 		"length": anim.length,

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

@@ -0,0 +1,134 @@
+@tool
+extends RefCounted
+
+const GdhRead = preload("reading.gd")
+
+# Two walks rather than one because they disagree about hidden entries on purpose: a suffix
+# walk descends into every visible directory and matches whole names, while the extension walk
+# skips anything beginning with a dot, including .import sidecars that would otherwise answer
+# for the resource they belong to.
+#
+# Both stop at a `.gdignore`, because the engine does: nothing under one is imported, so what is
+# in there is not a resource, not a dependency and not a global class. Walking in anyway hands
+# every caller files the engine will never answer for.
+
+
+# Why [param path], a res:// or uid:// path a setting names, is not a file the engine can load, or
+# empty when it is. A uid:// path resolves through the project's uid cache, which the import writes,
+# so one that does not resolve is a file that has gone or a project not imported yet, and saying
+# only that the file does not exist sent a caller looking for a scene that was there.
+static func missing_reason(path: String) -> String:
+	if path.begins_with("uid://"):
+		var id: int = ResourceUID.text_to_id(path)
+		if id == ResourceUID.INVALID_ID or not ResourceUID.has_id(id):
+			return (
+				path
+				+ " does not resolve: no file in the project's uid cache has it, so the file has gone or the"
+				+ " project has not been imported yet (project_import refresh_uids imports it)"
+			)
+		var resolved: String = ResourceUID.get_id_path(id)
+		return (
+			"" if FileAccess.file_exists(resolved) else path + " names " + resolved + ", which does not exist"
+		)
+	return "" if FileAccess.file_exists(path) else path + " does not exist"
+
+
+## [param said], the refusal for [param path], a res:// path nothing is at, with the files of its
+## extension whose names are nearest its own, or every one when there are few and none is near, so
+## the caller has a path to send instead.
+func with_nearest_files(said: String, path: String) -> String:
+	var extension: String = path.get_extension()
+	if extension.is_empty():
+		return said
+	var files: Array[String] = find_files_with_extensions("res://", [extension])
+	# The walk lists a directory in the order the filesystem keeps it, which differs between
+	# platforms, so the same project was answered with its files in another order on Linux.
+	files.sort()
+	if files.is_empty():
+		return "%s. The project holds no .%s file." % [said, extension]
+	var names: PackedStringArray = []
+	for file: String in files:
+		var _named: bool = names.append(file.get_file().get_basename())
+	var close: PackedStringArray = GdhRead.nearest(path.get_file().get_basename(), names)
+	var offered: PackedStringArray = []
+	for file: String in files:
+		if file.get_file().get_basename() in close:
+			var _offered: bool = offered.append(file)
+	if not offered.is_empty():
+		var one: bool = offered.size() == 1
+		return (
+			"%s. The nearest .%s %s %s."
+			% [said, extension, "file is" if one else "files are", ", ".join(offered)]
+		)
+	if files.size() <= GdhRead.NAMED_CHILDREN:
+		return "%s. The project's .%s files are %s." % [said, extension, ", ".join(files)]
+	return "%s. None of the project's %d .%s files is named like it." % [said, files.size(), extension]
+
+
+# A directory the engine steps over, marker file and all.
+func is_stepped_over(path: String) -> bool:
+	return FileAccess.file_exists(path + ".gdignore")
+
+
+# An addon gdharness installed, told by the marker setup writes into it. The engine loads it, but
+# nobody on the project wrote it: the health check counted its thirty-odd scripts as the project's,
+# 39 beside the 5 project_info's own count gave, which the server's walks already step over.
+func is_installed_by_gdharness(path: String) -> bool:
+	return FileAccess.file_exists(path + ".gdharness-version")
+
+
+# Files under `path` whose name ends with `extension`, which is passed with its dot.
+func find_files(path: String, extension: String) -> Array[String]:
+	var files: Array[String] = []
+	if is_stepped_over(path) or is_installed_by_gdharness(path):
+		return files
+
+	var dir: DirAccess = DirAccess.open(path)
+
+	if dir:
+		if dir.list_dir_begin() != OK:
+			return files
+		var file_name: String = 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
+
+
+# Files under `path` whose extension is in `extensions`, which are passed without their dot.
+func find_files_with_extensions(path: String, extensions: Array) -> Array[String]:
+	var files: Array[String] = []
+	if is_stepped_over(path) or is_installed_by_gdharness(path):
+		return files
+
+	var dir: DirAccess = DirAccess.open(path)
+
+	if dir:
+		if dir.list_dir_begin() != OK:
+			return files
+		var file_name: String = dir.get_next()
+
+		while file_name != "":
+			if file_name.begins_with("."):
+				file_name = dir.get_next()
+				continue
+
+			var full_path: String = path + file_name
+			if dir.current_is_dir():
+				files.append_array(find_files_with_extensions(full_path + "/", extensions))
+			else:
+				var ext: String = file_name.get_extension().to_lower()
+				if ext in extensions:
+					files.append(full_path)
+
+			file_name = dir.get_next()
+
+		dir.list_dir_end()
+
+	return files

package/build/godot/addons/gdharness_editor/file_walk.gd.uid

@@ -0,0 +1 @@
+uid://c16785cs9xozr

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

@@ -189,6 +189,7 @@ func write_all(target: Object, properties: Dictionary) -> String:
 		named[str(key).get_slice(":", 0)] = true
 	var before: Dictionary = _stored(target, named)
 	var given: Dictionary = {}
+	var declarations: Dictionary = {}
 	# A refusal of one of several leaves the others unwritten too, which a refusal naming only the
 	# one it refused left a caller to guess.
 	var unwritten: String = (
@@ -213,6 +214,7 @@ func write_all(target: Object, properties: Dictionary) -> String:
 			_outside_declared[property] = outside
 		_write(target, property, value[1])
 		given[property] = value[1]
+		declarations[property] = declared
 
 	for property: String in given:
 		if not same(read_at(target, property), given[property]):
@@ -220,13 +222,8 @@ func write_all(target: Object, properties: Dictionary) -> String:
 	for property: String in given:
 		var held: Variant = read_at(target, property)
 		if not same(held, given[property]):
-			return (
-				(
-					"%s.%s was given %s and holds %s after it was set: the engine changed or refused the "
-					+ "value, so nothing was written."
-				)
-				% [target.get_class(), property, shown(given[property]), shown(held)]
-			)
+			var declared: Dictionary = declarations[property]
+			return _not_held(target, property, given[property], held, declared)
 	for property: String in before:
 		var now: Variant = target.get(property)
 		if not same(now, before[property]):
@@ -234,6 +231,57 @@ func write_all(target: Object, properties: Dictionary) -> String:
 	return ""
 
 
+## Why [param property] of [param target], declared as [param declared], holds [param held] after
+## it was given [param value]. A text property with a list of names holds only one of them, and its
+## getter answers its default for any other. A player's bus is one, though the engine fills its list
+## only in the inspector, so the buses are read from the AudioServer, which holds the project's
+## layout; "the engine changed or refused the value" left a caller to guess the bus did not exist.
+func _not_held(
+	target: Object, property: String, value: Variant, held: Variant, declared: Dictionary
+) -> String:
+	var said: String = (
+		"%s.%s was given %s and holds %s after it was set"
+		% [target.get_class(), property, shown(value), shown(held)]
+	)
+	var type: int = GdhRead.as_int(declared.get("type", TYPE_NIL))
+	var hint: int = GdhRead.as_int(declared.get("hint", PROPERTY_HINT_NONE))
+	var names: PackedStringArray = []
+	if hint == PROPERTY_HINT_ENUM and (type == TYPE_STRING or type == TYPE_STRING_NAME):
+		names = PackedStringArray(GdhDeclared.enum_values(str(declared.get("hint_string", ""))).keys())
+	var bus: bool = property == "bus" and target.get_class().begins_with("AudioStreamPlayer")
+	if bus:
+		names = []
+		for index: int in AudioServer.bus_count:
+			var _added: bool = names.append(AudioServer.get_bus_name(index))
+	if names.is_empty() or names.has(str(value)):
+		return said + ": the engine changed or refused the value, so nothing was written."
+	var close: PackedStringArray = GdhRead.nearest(str(value), names)
+	var nearest: String = (
+		"%s %s" % ["is" if close.size() == 1 else "are", ", ".join(close)] if not close.is_empty() else ""
+	)
+	if bus:
+		return (
+			(
+				"%s: it takes the name of one of the project's audio buses, and %s is none of them; %s. "
+				+ "project_info include audio_buses lists them, and project_settings add_audio_bus adds "
+				+ "one. Nothing was written."
+			)
+			% [
+				said,
+				shown(value),
+				"the buses are " + ", ".join(names) if nearest.is_empty() else "the nearest " + nearest
+			]
+		)
+	return (
+		"%s: it takes one of the names it lists, and %s is none of them; %s. Nothing was written."
+		% [
+			said,
+			shown(value),
+			"it lists " + ", ".join(names) if nearest.is_empty() else "the nearest it lists " + nearest
+		]
+	)
+
+
 ## Why [param material] has no [param property]: a ShaderMaterial's parameters are its shader's
 ## uniforms, so the shader is what lacks one, and "ShaderMaterial has no property" named the
 ## material.

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

@@ -437,7 +437,9 @@ func unusable_name(parent: Node, child_name: String, moving: Node = null) -> Str
 		return unfit
 	var taken: Node = parent.get_node_or_null(NodePath(child_name))
 	if taken != null and taken != moving and taken.get_parent() == parent:
-		return "%s already has a child named %s." % [path_of(parent), child_name]
+		# The root by its name, since its path is ".", and ". already has a child" read as a typo.
+		var holder: String = "The root, %s," % parent.name if parent == root else path_of(parent)
+		return "%s already has a child named %s." % [holder, child_name]
 	return ""
 
 

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

@@ -124,6 +124,9 @@ func _init_tools() -> void:
 		"read_animation_states": [_animation_tools, "read_animation_states"],
 		"create_animation": [_animation_tools, "create_animation"],
 		"add_animation_track": [_animation_tools, "add_animation_track"],
+		"set_animation": [_animation_tools, "set_animation"],
+		"rename_animation": [_animation_tools, "rename_animation"],
+		"remove_animation": [_animation_tools, "remove_animation"],
 		"add_animation_state": [_animation_tools, "add_animation_state"],
 		"connect_animation_states": [_animation_tools, "connect_animation_states"],
 	}

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

@@ -14,6 +14,9 @@ const GdhSerialisation = preload("../serialisation.gd")
 ## How far right of the rightmost state a new one goes in the editor's graph, wider than a state's
 ## box there.
 const STATE_SPACING: float = 200.0
+const LOOP_MODES: Dictionary = {
+	"none": Animation.LOOP_NONE, "linear": Animation.LOOP_LINEAR, "pingpong": Animation.LOOP_PINGPONG
+}
 
 var _editor_plugin: EditorPlugin = null
 var _properties: GdhPropertyValues = GdhPropertyValues.new()
@@ -284,11 +287,12 @@ func create_animation(args: Dictionary) -> Dictionary:
 		return {"ok": false, "error": "Missing scenePath"}
 	if animation_name.strip_edges().is_empty():
 		return {"ok": false, "error": "Missing animationName"}
-	var loop_modes: Dictionary = {
-		"none": Animation.LOOP_NONE, "linear": Animation.LOOP_LINEAR, "pingpong": Animation.LOOP_PINGPONG
-	}
+	var loop_modes: Dictionary = LOOP_MODES
 	if not loop_modes.has(loop_mode_name):
 		return {"ok": false, "error": "Unsupported loopMode: " + loop_mode_name}
+	var timing: String = _timing_refusal(args)
+	if not timing.is_empty():
+		return {"ok": false, "error": timing}
 
 	var opened: Array = _open_at(scene_path, player_node_path, "AnimationPlayer")
 	var scene: GdhSceneFile = opened[0]
@@ -347,15 +351,13 @@ func add_animation_track(args: Dictionary) -> Dictionary:
 	if not keyed[0]:
 		return {"ok": false, "error": keyed[1]}
 
-	var opened: Array = _open_at(scene_path, player_node_path, "AnimationPlayer")
+	# Asked of the player, which knows every library: looking only in the default one refused
+	# "moves/walk" as missing.
+	var opened: Array = _animation_at(scene_path, player_node_path, animation_name)
 	var scene: GdhSceneFile = opened[0]
 	if opened[1] == null:
 		return opened[2]
 	var player: AnimationPlayer = opened[1]
-	# Asked of the player, which knows every library: looking only in the default one refused
-	# "moves/walk" as missing.
-	if not player.has_animation(StringName(animation_name)):
-		return scene.refuse("%s has no animation %s" % [player_node_path, animation_name])
 	var anim: Animation = player.get_animation(StringName(animation_name))
 	var homes: Array = _homes(
 		scene, [[_library_of(player, animation_name), "animation library"], [anim, "animation"]]
@@ -394,55 +396,129 @@ func add_animation_track(args: Dictionary) -> Dictionary:
 			return "the track would not be in %s when the scene loads." % animation_name
 		return ""
 	var answer: Dictionary = {
-		"ok": true, "trackType": str(track.get("type", "")), "trackIndex": track_idx, "keys": keys
+		"ok": true,
+		"trackType": str(track.get("type", "")),
+		"trackIndex": track_idx,
+		"keys": keys,
+		"keysAdded": keyframes.size(),
 	}
+	if built[3]:
+		answer["existingTrack"] = true
 	if built[2] != null:
 		answer["methodFound"] = built[2]
+	var past: String = _past_length(anim, animation_name)
+	if not past.is_empty():
+		answer["pastLength"] = past
 	var files: Dictionary = homes[1]
 	return _finish(scene, check, files, answer)
 
 
-## Adds [param track] to [param anim] with [param keyframes], as [index, why not, methodFound]:
-## methodFound is null for a property track.
+## Adds [param track] to [param anim] with [param keyframes], as [index, why not, methodFound,
+## existing]: methodFound is null for a property track, and existing is whether the keys went into
+## a track the animation already had for that path.
+##
+## Into that track rather than a second one beside it, as the editor keys a property it already
+## animates: two tracks for one path both play, the later overriding the earlier, and a key meant
+## to extend the motion was split off where reading the animation showed two halves.
 func _add_track(
 	anim: Animation, track: Dictionary, target: Node, target_path: String, keyframes: Array
 ) -> Array:
 	var track_type: String = str(track.get("type", ""))
 	var keys: Array = []
 	var method_found: Variant = null
-	var track_idx: int = -1
+	var kind: Animation.TrackType = Animation.TYPE_VALUE
+	var path: NodePath = NodePath(target_path)
 	if track_type == "property":
 		var prop_name: String = str(track.get("property", ""))
 		if prop_name.is_empty():
-			return [-1, "track.property is required for property track", null]
+			return [-1, "track.property is required for property track", null, false]
 		var values: Array = _key_values(target, prop_name, keyframes)
 		if not values[0]:
-			return [-1, values[1], null]
+			return [-1, values[1], null, false]
 		keys = values[1]
-		track_idx = anim.add_track(Animation.TYPE_VALUE)
-		anim.track_set_path(track_idx, NodePath(target_path + ":" + prop_name))
+		path = NodePath(target_path + ":" + prop_name)
 	elif track_type == "method":
 		var method_name: String = str(track.get("method", ""))
 		if method_name.is_empty():
-			return [-1, "track.method is required for method track", null]
+			return [-1, "track.method is required for method track", null, false]
 		for index: int in keyframes.size():
 			var keyframe: Dictionary = keyframes[index]
 			var given: Variant = keyframe.get("args", [])
 			if not given is Array:
-				return [-1, "keyframes[%d].args must be a list." % index, null]
+				return [-1, "keyframes[%d].args must be a list." % index, null, false]
 			var arguments: Array = given
 			keys.append({"method": method_name, "args": _parse_method_args(arguments)})
 		method_found = target.has_method(method_name)
-		track_idx = anim.add_track(Animation.TYPE_METHOD)
-		anim.track_set_path(track_idx, NodePath(target_path))
+		kind = Animation.TYPE_METHOD
 	else:
-		return [-1, "Unsupported track.type: " + track_type, null]
+		return [-1, "Unsupported track.type: " + track_type, null, false]
 
+	var track_idx: int = anim.find_track(path, kind)
+	var existing: bool = track_idx >= 0
+	if existing:
+		# Checked before any key goes in, since track_insert_key replaces a key at the same time
+		# without a word, and a refusal partway would leave the editor's scene half changed.
+		for index: int in keyframes.size():
+			var keyframe: Dictionary = keyframes[index]
+			var time: float = GdhRead.as_float(keyframe["time"])
+			if anim.track_find_key(track_idx, time, Animation.FIND_MODE_APPROX) >= 0:
+				return [
+					-1,
+					(
+						(
+							"Track %d already animates %s and has a key at %s s, which keyframes[%d] would "
+							+ "replace. Nothing was written."
+						)
+						% [track_idx, str(path), _seconds(time), index]
+					),
+					null,
+					false
+				]
+	else:
+		track_idx = anim.add_track(kind)
+		anim.track_set_path(track_idx, path)
 	for index: int in keyframes.size():
 		var keyframe: Dictionary = keyframes[index]
 		if anim.track_insert_key(track_idx, GdhRead.as_float(keyframe["time"]), keys[index]) < 0:
-			return [-1, "Keyframe %d could not be inserted." % index, null]
-	return [track_idx, "", method_found]
+			return [-1, "Keyframe %d could not be inserted." % index, null, false]
+	return [track_idx, "", method_found, existing]
+
+
+## The keys of [param anim], called [param animation_name], that lie past its end, where they never
+## play, as a sentence naming each by its track's path and time, or "" when none does. The engine
+## keeps such a key, as the editor does, so a longer length plays it again.
+static func _past_length(anim: Animation, animation_name: String) -> String:
+	var past: PackedStringArray = []
+	for track: int in anim.get_track_count():
+		for key: int in anim.track_get_key_count(track):
+			var time: float = anim.track_get_key_time(track, key)
+			if time > anim.length + 0.0001:
+				var _added: bool = past.append(
+					"%s at %s s" % [str(anim.track_get_path(track)), _seconds(time)]
+				)
+	if past.is_empty():
+		return ""
+	return (
+		(
+			"%s is %s s long, and %s past its end, where %s: %s. %s; scene_animation set "
+			+ "with a longer length plays %s."
+		)
+		% [
+			animation_name,
+			_seconds(anim.length),
+			"this key is" if past.size() == 1 else "these keys are",
+			"it never plays" if past.size() == 1 else "they never play",
+			", ".join(past),
+			"It is kept" if past.size() == 1 else "They are kept",
+			"it" if past.size() == 1 else "them",
+		]
+	)
+
+
+## [param seconds] as a caller wrote it: a key at 2 reads 2, not 2.0.
+static func _seconds(seconds: float) -> String:
+	var rounded: float = snappedf(seconds, 0.0001)
+	return str(int(rounded)) if rounded == floorf(rounded) else str(rounded)
 
 
 ## The keyframes of [param track], as [true, list] or [false, why]. Each needs its own time: one
@@ -496,6 +572,274 @@ func _key_values(target: Node, prop_name: String, keyframes: Array) -> Array:
 	return [true, values]
 
 
+# =============================================================================
+# set_animation, rename_animation, remove_animation
+# =============================================================================
+## Why the length or step in [param args] cannot be taken, or "". The engine raises a length below
+## a thousandth of a second to that without a word.
+static func _timing_refusal(args: Dictionary) -> String:
+	if args.has("length"):
+		var length: Variant = args["length"]
+		if not (length is float or length is int) or GdhRead.as_float(length) <= 0.0:
+			return "length is the animation's length in seconds, more than 0, and %s is not." % _given(length)
+	if args.has("step"):
+		var step: Variant = args["step"]
+		if not (step is float or step is int) or GdhRead.as_float(step) < 0.0:
+			return "step is the keyframe snap in seconds, 0 or more, and %s is not." % _given(step)
+	return ""
+
+
+static func _given(value: Variant) -> String:
+	if value is float or value is int:
+		return _seconds(GdhRead.as_float(value))
+	return JSON.stringify(value)
+
+
+## [param scene_path] opened for writing with the player at [param player_node_path], which must
+## have [param animation_name], as [method _open_at] answers.
+func _animation_at(scene_path: String, player_node_path: String, animation_name: String) -> Array:
+	var opened: Array = _open_at(scene_path, player_node_path, "AnimationPlayer")
+	if opened[1] == null:
+		return opened
+	var scene: GdhSceneFile = opened[0]
+	var player: AnimationPlayer = opened[1]
+	if player.has_animation(StringName(animation_name)):
+		return opened
+	var said: String = GdhAnimationReads.no_animation(player, player_node_path, animation_name)
+	return [scene, null, scene.refuse(said)]
+
+
+## Changes the length, loop mode or step of an animation, naming any key a shorter length leaves
+## past the end.
+func set_animation(args: Dictionary) -> Dictionary:
+	var scene_path: String = _ensure_res_path(str(args.get("scenePath", "")))
+	var player_node_path: String = str(args.get("playerNodePath", "."))
+	var animation_name: String = str(args.get("animationName", ""))
+	var loop_mode_name: String = str(args.get("loopMode", ""))
+	if scene_path.strip_edges() == "res://":
+		return {"ok": false, "error": "Missing scenePath"}
+	if animation_name.strip_edges().is_empty():
+		return {"ok": false, "error": "Missing animationName"}
+	if not (args.has("length") or args.has("loopMode") or args.has("step")):
+		return {"ok": false, "error": "set changes length, loopMode or step, and was given none of them."}
+	if args.has("loopMode") and not LOOP_MODES.has(loop_mode_name):
+		return {"ok": false, "error": "Unsupported loopMode: " + loop_mode_name}
+	var timing: String = _timing_refusal(args)
+	if not timing.is_empty():
+		return {"ok": false, "error": timing}
+
+	var found: Array = _animation_at(scene_path, player_node_path, animation_name)
+	if found[1] == null:
+		return found[2]
+	var scene: GdhSceneFile = found[0]
+	var player: AnimationPlayer = found[1]
+	var anim: Animation = player.get_animation(StringName(animation_name))
+	var homes: Array = _homes(
+		scene, [[_library_of(player, animation_name), "animation library"], [anim, "animation"]]
+	)
+	if not homes[0]:
+		return scene.refuse(str(homes[1]))
+	if args.has("length"):
+		anim.length = GdhRead.as_float(args["length"])
+	if args.has("loopMode"):
+		anim.loop_mode = GdhRead.as_int(LOOP_MODES[loop_mode_name]) as Animation.LoopMode
+	if args.has("step"):
+		anim.step = GdhRead.as_float(args["step"])
+
+	var length: float = anim.length
+	var at: String = scene.path_of(player)
+	var check: Callable = func(saved: Node) -> String:
+		var copy: AnimationPlayer = saved.get_node_or_null(at) as AnimationPlayer
+		if copy == null or not copy.has_animation(StringName(animation_name)):
+			return "%s would not be in the scene when it loads." % animation_name
+		if not is_equal_approx(copy.get_animation(StringName(animation_name)).length, length):
+			return "%s would not be %s s long when the scene loads." % [animation_name, _seconds(length)]
+		return ""
+	var answer: Dictionary = {
+		"ok": true,
+		"animationName": animation_name,
+		"length": anim.length,
+		"loopMode": GdhAnimationReads.LOOP_MODE_NAMES.get(anim.loop_mode, str(anim.loop_mode)),
+		"step": anim.step,
+	}
+	var past: String = _past_length(anim, animation_name)
+	if not past.is_empty():
+		answer["pastLength"] = past
+	var files: Dictionary = homes[1]
+	return _finish(scene, check, files, answer)
+
+
+## Renames an animation within its library, taking along the player's autoplay and every state of
+## the scene's trees that plays it, since a state naming an animation the player lacks plays nothing
+## and says so only in the editor's log.
+func rename_animation(args: Dictionary) -> Dictionary:
+	var scene_path: String = _ensure_res_path(str(args.get("scenePath", "")))
+	var player_node_path: String = str(args.get("playerNodePath", "."))
+	var animation_name: String = str(args.get("animationName", ""))
+	var new_name: String = str(args.get("newName", "")).strip_edges()
+	if scene_path.strip_edges() == "res://":
+		return {"ok": false, "error": "Missing scenePath"}
+	if animation_name.strip_edges().is_empty():
+		return {"ok": false, "error": "Missing animationName"}
+	if new_name.is_empty():
+		return {"ok": false, "error": "Missing newName"}
+	var library_name: String = animation_name.get_slice("/", 0) if animation_name.contains("/") else ""
+	var prefix: String = "" if library_name.is_empty() else library_name + "/"
+	if not prefix.is_empty() and new_name.begins_with(prefix):
+		new_name = new_name.trim_prefix(prefix)
+	if new_name.contains("/"):
+		return {
+			"ok": false,
+			"error":
+			(
+				(
+					"rename keeps an animation in its library (%s), so newName is its name there, with "
+					+ "no library before a slash."
+				)
+				% ("the default one" if library_name.is_empty() else library_name)
+			),
+		}
+	for forbidden: String in [":", ",", "["]:
+		if new_name.contains(forbidden):
+			return {"ok": false, "error": "An animation's name cannot hold : , or [, and %s does." % new_name}
+	var new_full: String = prefix + new_name
+
+	var found: Array = _animation_at(scene_path, player_node_path, animation_name)
+	if found[1] == null:
+		return found[2]
+	var scene: GdhSceneFile = found[0]
+	var player: AnimationPlayer = found[1]
+	if new_full == animation_name:
+		return scene.refuse("%s is already called %s." % [animation_name, new_full])
+	if player.has_animation(StringName(new_full)):
+		return scene.refuse("%s already has an animation %s." % [player_node_path, new_full])
+	var library: AnimationLibrary = _library_of(player, animation_name)
+	var states: Array = _states_playing(scene, player, animation_name)
+	var held: Array = [[library, "animation library"]]
+	for state: Array in states:
+		held.append([state[0], "state playing %s" % animation_name])
+	var homes: Array = _homes(scene, held)
+	if not homes[0]:
+		return scene.refuse(str(homes[1]))
+
+	# Read before the rename, since the player moves its autoplay to the new name on its own; it
+	# does not clear one when an animation is removed.
+	var autoplayed: bool = str(player.autoplay) == animation_name
+	library.rename_animation(StringName(animation_name.trim_prefix(prefix)), StringName(new_name))
+	if not player.has_animation(StringName(new_full)):
+		return scene.refuse("The library did not take the name %s." % new_full)
+	var answer: Dictionary = {"ok": true, "animationName": new_full, "was": animation_name}
+	if autoplayed:
+		answer["autoplay"] = new_full
+	var followed: Array = []
+	for state: Array in states:
+		var plays: AnimationNodeAnimation = state[0]
+		plays.animation = StringName(new_full)
+		followed.append(state[1])
+	if not followed.is_empty():
+		answer["statesFollowed"] = followed
+
+	var at: String = scene.path_of(player)
+	var check: Callable = func(saved: Node) -> String:
+		var copy: AnimationPlayer = saved.get_node_or_null(at) as AnimationPlayer
+		if copy == null or not copy.has_animation(StringName(new_full)):
+			return "%s would not be in the scene when it loads." % new_full
+		return ""
+	var files: Dictionary = homes[1]
+	return _finish(scene, check, files, answer)
+
+
+## Removes an animation, clearing the player's autoplay when it named it and naming the states of
+## the scene's trees left playing nothing.
+func remove_animation(args: Dictionary) -> Dictionary:
+	var scene_path: String = _ensure_res_path(str(args.get("scenePath", "")))
+	var player_node_path: String = str(args.get("playerNodePath", "."))
+	var animation_name: String = str(args.get("animationName", ""))
+	if scene_path.strip_edges() == "res://":
+		return {"ok": false, "error": "Missing scenePath"}
+	if animation_name.strip_edges().is_empty():
+		return {"ok": false, "error": "Missing animationName"}
+
+	var found: Array = _animation_at(scene_path, player_node_path, animation_name)
+	if found[1] == null:
+		return found[2]
+	var scene: GdhSceneFile = found[0]
+	var player: AnimationPlayer = found[1]
+	var library: AnimationLibrary = _library_of(player, animation_name)
+	var homes: Array = _homes(scene, [[library, "animation library"]])
+	if not homes[0]:
+		return scene.refuse(str(homes[1]))
+	var called: String = animation_name.get_slice("/", 1) if animation_name.contains("/") else animation_name
+	var autoplayed: bool = str(player.autoplay) == animation_name
+	library.remove_animation(StringName(called))
+	if player.has_animation(StringName(animation_name)):
+		return scene.refuse("The library did not let go of %s." % animation_name)
+	var answer: Dictionary = {"ok": true, "removed": animation_name}
+	if autoplayed:
+		player.autoplay = ""
+		answer["autoplayCleared"] = true
+	var orphaned: Array = []
+	for state: Array in _states_playing(scene, player, animation_name):
+		orphaned.append(state[1])
+	if not orphaned.is_empty():
+		answer["statesPlayingNothing"] = orphaned
+
+	var at: String = scene.path_of(player)
+	var check: Callable = func(saved: Node) -> String:
+		var copy: AnimationPlayer = saved.get_node_or_null(at) as AnimationPlayer
+		if copy == null or copy.has_animation(StringName(animation_name)):
+			return "%s would still be in the scene when it loads." % animation_name
+		return ""
+	var files: Dictionary = homes[1]
+	return _finish(scene, check, files, answer)
+
+
+## The states of [param scene]'s AnimationTrees that play [param animation_name] from [param player],
+## as [[node, {animTreePath, state}]], a state named by the path of the nodes leading to it.
+func _states_playing(scene: GdhSceneFile, player: AnimationPlayer, animation_name: String) -> Array:
+	var found: Array = []
+	var trees: Array[Node] = scene.root.find_children("*", "AnimationTree", true, false)
+	if scene.root is AnimationTree:
+		trees.append(scene.root)
+	for node: Node in trees:
+		var tree: AnimationTree = node
+		if tree.tree_root == null or tree.get_node_or_null(tree.anim_player) != player:
+			continue
+		var tree_path: String = str(scene.root.get_path_to(tree))
+		_collect_playing(tree.tree_root, "", tree_path, animation_name, found)
+	return found
+
+
+static func _collect_playing(
+	node: AnimationNode, at: String, tree_path: String, animation_name: String, found: Array
+) -> void:
+	if node is AnimationNodeAnimation:
+		var plays: AnimationNodeAnimation = node
+		if plays.animation == StringName(animation_name):
+			found.append([plays, {"animTreePath": tree_path, "state": "." if at.is_empty() else at}])
+		return
+	var children: Dictionary = {}
+	if node is AnimationNodeStateMachine:
+		var machine: AnimationNodeStateMachine = node
+		for state: StringName in machine.get_node_list():
+			children[str(state)] = machine.get_node(state)
+	elif node is AnimationNodeBlendTree:
+		var blend: AnimationNodeBlendTree = node
+		for input: StringName in blend.get_node_list():
+			children[str(input)] = blend.get_node(input)
+	elif node is AnimationNodeBlendSpace1D:
+		var line: AnimationNodeBlendSpace1D = node
+		for point: int in line.get_blend_point_count():
+			children[str(point)] = line.get_blend_point_node(point)
+	elif node is AnimationNodeBlendSpace2D:
+		var plane: AnimationNodeBlendSpace2D = node
+		for point: int in plane.get_blend_point_count():
+			children[str(point)] = plane.get_blend_point_node(point)
+	for step: String in children:
+		var child: AnimationNode = children[step]
+		_collect_playing(child, step if at.is_empty() else at + "/" + step, tree_path, animation_name, found)
+
+
 # =============================================================================
 # add_animation_state
 # =============================================================================

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

@@ -4,6 +4,7 @@ extends RefCounted
 ## What a new node in a scene is made or copied from, what the scene owns of it, and where among its
 ## siblings a node may go.
 
+const GdhFileWalk = preload("../file_walk.gd")
 const GdhRead = preload("../reading.gd")
 const GdhPropertyValues = preload("../property_values.gd")
 
@@ -17,11 +18,15 @@ static func what_to_add(node_type: String, instance_path: String, scene_path: St
 			"add takes nodeType for a node of a class, or instancePath for a scene, and one of them only."
 		]
 	if not instance_path.is_empty():
+		# Asked before the cycle walk, which reads the file's dependencies and so loaded a file that
+		# was not there, laying the engine's error and a backtrace beneath the refusal.
+		if not ResourceLoader.exists(instance_path, "PackedScene"):
+			var said: String = "No scene at %s to instance" % instance_path
+			var offered: String = GdhFileWalk.new().with_nearest_files(said, instance_path)
+			return [null, offered if offered != said else said + "."]
 		var cycle: String = _instancing_cycle(scene_path, instance_path)
 		if not cycle.is_empty():
 			return [null, cycle]
-		if not ResourceLoader.exists(instance_path, "PackedScene"):
-			return [null, "No scene at %s to instance." % instance_path]
 		var packed: PackedScene = ResourceLoader.load(instance_path, "PackedScene") as PackedScene
 		if packed == null or not packed.can_instantiate():
 			return [null, "%s does not load as a scene that can be instanced." % instance_path]
@@ -35,12 +40,24 @@ static func what_to_add(node_type: String, instance_path: String, scene_path: St
 			)
 		]
 	if not ClassDB.class_exists(node_type) or not ClassDB.is_parent_class(node_type, "Node"):
-		return [null, "nodeType must be a node class, and %s is not one." % node_type]
+		return [null, not_a_node_class("nodeType", node_type)]
 	if not ClassDB.can_instantiate(node_type):
 		return [null, "%s cannot be instantiated." % node_type]
 	return [null, ""]
 
 
+## The refusal for [param given], sent as [param argument], which names no node class, with the
+## node classes nearest it, so "Node2DD" is offered Node2D.
+static func not_a_node_class(argument: String, given: String) -> String:
+	var said: String = "%s must be a node class, and %s is not one" % [argument, given]
+	var classes: PackedStringArray = ClassDB.get_inheriters_from_class("Node")
+	var _added: bool = classes.append("Node")
+	var close: PackedStringArray = GdhRead.nearest(given, classes)
+	if close.is_empty():
+		return said + "."
+	return "%s; the nearest %s %s." % [said, "is" if close.size() == 1 else "are", ", ".join(close)]
+
+
 ## A new node of [param node_type], or an instance of [param packed] when there is one. The instance
 ## is made in the editor's edit state, so the pack writes it as an instance of its file, and owning
 ## its root leaves its own nodes to the instanced scene.

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

@@ -202,9 +202,7 @@ func _create_of_a_class(args: Dictionary) -> Dictionary:
 	# A class that is not a node went into a Node variable, which is a runtime error the caller
 	# heard about only as "Invalid tool result".
 	if not ClassDB.class_exists(root_node_type) or not ClassDB.is_parent_class(root_node_type, "Node"):
-		return {
-			"ok": false, "error": "rootNodeType must be a node class, and %s is not one." % root_node_type
-		}
+		return {"ok": false, "error": GdhPlacing.not_a_node_class("rootNodeType", root_node_type)}
 	if not ClassDB.can_instantiate(root_node_type):
 		return {"ok": false, "error": "%s cannot be instantiated." % root_node_type}
 	var unfit: String = GdhSceneFile.unfit_name(root_node_name)
@@ -243,6 +241,7 @@ func _create_of_a_class(args: Dictionary) -> Dictionary:
 		# name is no property the write compares.
 		root.name = root_node_name
 
+	var had_folder: bool = DirAccess.dir_exists_absolute(scene_path.get_base_dir())
 	var folder: String = GdhSceneFile.make_folder_for(scene_path)
 	if not folder.is_empty():
 		root.free()
@@ -251,7 +250,12 @@ func _create_of_a_class(args: Dictionary) -> Dictionary:
 	if not written.is_empty():
 		return written
 
-	return {"ok": true, "scenePath": scene_path, "rootNodeType": asked_type, "rootNodeName": root_node_name}
+	var answer: Dictionary = {
+		"ok": true, "scenePath": scene_path, "rootNodeType": asked_type, "rootNodeName": root_node_name
+	}
+	if not had_folder:
+		answer["madeFolder"] = scene_path.get_base_dir()
+	return answer
 
 
 func list_scene_nodes(args: Dictionary) -> Dictionary:

package/build/godot/operations/animation_reads.gd

@@ -81,15 +81,7 @@ static func animations(player: AnimationPlayer, animation_name: String) -> Dicti
 			listed.append(summary)
 		return {"ok": true, "animations": listed}
 	if not player.has_animation(StringName(animation_name)):
-		var names: PackedStringArray = player.get_animation_list()
-		return {
-			"ok": false,
-			"error":
-			(
-				"%s has no animation %s. It has: %s."
-				% [player.name, animation_name, ", ".join(names) if not names.is_empty() else "none"]
-			)
-		}
+		return {"ok": false, "error": no_animation(player, str(player.name), animation_name)}
 	var anim: Animation = player.get_animation(StringName(animation_name))
 	var answer: Dictionary = _summary(anim)
 	answer["ok"] = true
@@ -102,6 +94,16 @@ static func animations(player: AnimationPlayer, animation_name: String) -> Dicti
 	return answer
 
 
+## Why [param player], called [param called], cannot be asked for [param animation_name], with the
+## animations it has.
+static func no_animation(player: AnimationPlayer, called: String, animation_name: String) -> String:
+	var names: PackedStringArray = player.get_animation_list()
+	return (
+		"%s has no animation %s. It has: %s."
+		% [called, animation_name, ", ".join(names) if not names.is_empty() else "none"]
+	)
+
+
 static func _summary(anim: Animation) -> Dictionary:
 	return {
 		"length": anim.length,

package/build/godot/operations/editor_tools.gd

@@ -37,6 +37,9 @@ const RESOURCE_COMMANDS: Array[String] = [
 const ANIMATION_COMMANDS: Array[String] = [
 	"create_animation",
 	"add_animation_track",
+	"set_animation",
+	"rename_animation",
+	"remove_animation",
 	"add_animation_state",
 	"connect_animation_states",
 ]

package/build/godot/operations/file_walk.gd

@@ -1,3 +1,4 @@
+@tool
 extends RefCounted
 
 const GdhRead = preload("reading.gd")

package/build/godot/operations/property_values.gd

@@ -189,6 +189,7 @@ func write_all(target: Object, properties: Dictionary) -> String:
 		named[str(key).get_slice(":", 0)] = true
 	var before: Dictionary = _stored(target, named)
 	var given: Dictionary = {}
+	var declarations: Dictionary = {}
 	# A refusal of one of several leaves the others unwritten too, which a refusal naming only the
 	# one it refused left a caller to guess.
 	var unwritten: String = (
@@ -213,6 +214,7 @@ func write_all(target: Object, properties: Dictionary) -> String:
 			_outside_declared[property] = outside
 		_write(target, property, value[1])
 		given[property] = value[1]
+		declarations[property] = declared
 
 	for property: String in given:
 		if not same(read_at(target, property), given[property]):
@@ -220,13 +222,8 @@ func write_all(target: Object, properties: Dictionary) -> String:
 	for property: String in given:
 		var held: Variant = read_at(target, property)
 		if not same(held, given[property]):
-			return (
-				(
-					"%s.%s was given %s and holds %s after it was set: the engine changed or refused the "
-					+ "value, so nothing was written."
-				)
-				% [target.get_class(), property, shown(given[property]), shown(held)]
-			)
+			var declared: Dictionary = declarations[property]
+			return _not_held(target, property, given[property], held, declared)
 	for property: String in before:
 		var now: Variant = target.get(property)
 		if not same(now, before[property]):
@@ -234,6 +231,57 @@ func write_all(target: Object, properties: Dictionary) -> String:
 	return ""
 
 
+## Why [param property] of [param target], declared as [param declared], holds [param held] after
+## it was given [param value]. A text property with a list of names holds only one of them, and its
+## getter answers its default for any other. A player's bus is one, though the engine fills its list
+## only in the inspector, so the buses are read from the AudioServer, which holds the project's
+## layout; "the engine changed or refused the value" left a caller to guess the bus did not exist.
+func _not_held(
+	target: Object, property: String, value: Variant, held: Variant, declared: Dictionary
+) -> String:
+	var said: String = (
+		"%s.%s was given %s and holds %s after it was set"
+		% [target.get_class(), property, shown(value), shown(held)]
+	)
+	var type: int = GdhRead.as_int(declared.get("type", TYPE_NIL))
+	var hint: int = GdhRead.as_int(declared.get("hint", PROPERTY_HINT_NONE))
+	var names: PackedStringArray = []
+	if hint == PROPERTY_HINT_ENUM and (type == TYPE_STRING or type == TYPE_STRING_NAME):
+		names = PackedStringArray(GdhDeclared.enum_values(str(declared.get("hint_string", ""))).keys())
+	var bus: bool = property == "bus" and target.get_class().begins_with("AudioStreamPlayer")
+	if bus:
+		names = []
+		for index: int in AudioServer.bus_count:
+			var _added: bool = names.append(AudioServer.get_bus_name(index))
+	if names.is_empty() or names.has(str(value)):
+		return said + ": the engine changed or refused the value, so nothing was written."
+	var close: PackedStringArray = GdhRead.nearest(str(value), names)
+	var nearest: String = (
+		"%s %s" % ["is" if close.size() == 1 else "are", ", ".join(close)] if not close.is_empty() else ""
+	)
+	if bus:
+		return (
+			(
+				"%s: it takes the name of one of the project's audio buses, and %s is none of them; %s. "
+				+ "project_info include audio_buses lists them, and project_settings add_audio_bus adds "
+				+ "one. Nothing was written."
+			)
+			% [
+				said,
+				shown(value),
+				"the buses are " + ", ".join(names) if nearest.is_empty() else "the nearest " + nearest
+			]
+		)
+	return (
+		"%s: it takes one of the names it lists, and %s is none of them; %s. Nothing was written."
+		% [
+			said,
+			shown(value),
+			"it lists " + ", ".join(names) if nearest.is_empty() else "the nearest it lists " + nearest
+		]
+	)
+
+
 ## Why [param material] has no [param property]: a ShaderMaterial's parameters are its shader's
 ## uniforms, so the shader is what lacks one, and "ShaderMaterial has no property" named the
 ## material.

package/package.json

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