gdharness 1.3.3 → 1.3.5

package/build/godot/operations/gdscript_authoring.gd

@@ -7,6 +7,12 @@ const GdhPatterns = preload("patterns.gd")
 const GdhScriptCheck = preload("script_check.gd")
 
 const MODIFICATION_TYPES: Array[String] = ["add_constant", "add_variable", "add_signal", "add_function"]
+## The class each template's code is written for, and the base a script made from it extends
+## when given none: the resource template's code is a Resource's, and on the default of Node it
+## does not parse.
+const TEMPLATE_BASES: Dictionary = {
+	"singleton": "Node", "state_machine": "Node", "component": "Node", "resource": "Resource"
+}
 const BLANKS_AROUND_FUNCTIONS: int = 2
 
 var _log: GdhLog
@@ -20,11 +26,11 @@ func _init(p_log: GdhLog) -> void:
 func create_gdscript(params: Dictionary) -> Dictionary:
 	var script_path: String = str(params.get("script_path", ""))
 	var cls_name_param: String = str(params.get("class_name", ""))
-	var extends_class: String = str(params.get("extends", "Node"))
-	if extends_class.is_empty():
-		extends_class = "Node"
 	var content: String = str(params.get("content", ""))
 	var template: String = str(params.get("template", ""))
+	var extends_class: String = str(params.get("extends", ""))
+	if extends_class.is_empty():
+		extends_class = str(TEMPLATE_BASES.get(template, "Node"))
 
 	_log.info("Creating GDScript: " + script_path)
 
@@ -51,7 +57,7 @@ func create_gdscript(params: Dictionary) -> Dictionary:
 		full_script_path = "res://" + full_script_path
 
 	if not full_script_path.ends_with(".gd"):
-		return _log.failure("Script path must end with .gd extension")
+		return _log.failure(_not_gdscript(full_script_path, "makes"))
 
 	if FileAccess.file_exists(full_script_path):
 		return _log.failure(
@@ -62,6 +68,8 @@ func create_gdscript(params: Dictionary) -> Dictionary:
 	# and the first does not compile until the second exists.
 	if content.is_empty():
 		var header: String = _header_refusal(cls_name_param, extends_class)
+		if header.is_empty() and not template.is_empty():
+			header = _template_refusal(template, extends_class, full_script_path)
 		if not header.is_empty():
 			return _log.failure(header + " Nothing was written.")
 
@@ -80,8 +88,9 @@ func create_gdscript(params: Dictionary) -> Dictionary:
 		script_content += "extends " + extends_class + "\n"
 		# Only what was asked for: with no template the file was given an empty _ready beside a
 		# template_used of "none", which a caller had then to delete or leave lying in the script.
+		# Each template opens with the class's doc comment, which belongs straight below the header.
 		if not template.is_empty():
-			script_content += "\n" + _script_template(template)
+			script_content += _script_template(template)
 
 	var file: FileAccess = FileAccess.open(full_script_path, FileAccess.WRITE)
 	if not file:
@@ -93,21 +102,56 @@ func create_gdscript(params: Dictionary) -> Dictionary:
 		return _log.failure("Failed to write to script file: " + full_script_path)
 
 	var written: Script = ResourceLoader.load(full_script_path, "Script", ResourceLoader.CACHE_MODE_IGNORE)
+	var parses: bool = _parses(written)
 	var answer: Dictionary = {
 		"success": true,
 		"script_path": script_path,
 		"full_path": full_script_path,
 		"absolute_path": ProjectSettings.globalize_path(full_script_path),
 		"template_used": template if not template.is_empty() else "none",
-		"parses": _parses(written),
+		"parses": parses,
 	}
-	# Read off the file as the engine parsed it rather than off the arguments, which content leaves out.
-	if written != null:
+	# Read off the file as the engine parsed it rather than off the arguments, which content leaves
+	# out. A script that does not parse tells the engine nothing, and its empty base and name were
+	# answered for a file whose header says otherwise, so those are read off the text instead.
+	if parses:
 		answer["extends"] = _base_named(written)
 		answer["class_name"] = str(written.get_global_name())
+	else:
+		answer.merge(_header_written(script_content))
 	return answer
 
 
+## The refusal for [param path], which is no GDScript file, naming what [param doing] it instead:
+## a shader is made with resource_edit, and once it exists its text is edited as a file's.
+static func _not_gdscript(path: String, doing: String) -> String:
+	var refusal: String = "%s is not a .gd file, and script_edit %s GDScript only." % [path, doing]
+	if path.get_extension() != "gdshader":
+		return refusal
+	if doing == "makes":
+		return refusal + " resource_edit create_shader makes a shader, with its source as code."
+	return refusal + " A shader's text is edited as a file."
+
+
+## The class_name and extends [param text] declares at its margin, as written. A script with no
+## extends extends RefCounted.
+static func _header_written(text: String) -> Dictionary:
+	var header: Dictionary = {"extends": "RefCounted", "class_name": ""}
+	for line: String in text.split("\n"):
+		# An inner class's extends is indented, and is not the script's.
+		if line.begins_with(" ") or line.begins_with("\t"):
+			continue
+		var bare: String = GdhPatterns.without_annotations(GdhPatterns.without_comment(line))
+		var found: RegExMatch = GdhPatterns.declared_class(bare)
+		if found != null:
+			header["class_name"] = found.get_string(1)
+			if not found.get_string(2).is_empty():
+				header["extends"] = found.get_string(2)
+		elif bare.begins_with("extends "):
+			header["extends"] = bare.substr(8).strip_edges()
+	return header
+
+
 # Modify an existing GDScript file by adding functions, variables, or signals
 func modify_gdscript(params: Dictionary) -> Dictionary:
 	var script_path: String = str(params.get("script_path", ""))
@@ -119,6 +163,9 @@ func modify_gdscript(params: Dictionary) -> Dictionary:
 	if not full_script_path.begins_with("res://"):
 		full_script_path = "res://" + full_script_path
 
+	if not full_script_path.ends_with(".gd"):
+		return _log.failure(_not_gdscript(full_script_path, "changes"))
+
 	if not FileAccess.file_exists(full_script_path):
 		return _log.failure(
 			GdhFileWalk.new().with_nearest_files(
@@ -135,14 +182,22 @@ func modify_gdscript(params: Dictionary) -> Dictionary:
 
 	var lines: Array[String] = []
 	lines.assign(original_content.split("\n"))
+	# Loaded only to learn whether it parsed as it was. What the engine says of that file carries its
+	# old line numbers, and beside the errors of the file written it named lines that had moved.
+	printerr(GdhLog.ASIDE)
 	var before: Script = ResourceLoader.load(full_script_path, "Script", ResourceLoader.CACHE_MODE_IGNORE)
+	printerr(GdhLog.RESUMED)
 	var parsed_before: bool = _parses(before)
 
 	# All of them checked before any is made, so a call is made whole or not at all: one skipped for a
 	# missing name used to leave the rest written and the answer saying success over an empty list.
-	var problems: Array[String] = _modification_problems(modifications, _declared(lines))
+	var declared: Dictionary = _declared(lines)
+	var problems: Array[String] = _modification_problems(modifications, declared)
 	if not problems.is_empty():
-		return _log.failure("Nothing was changed: " + "; ".join(problems))
+		var refusal: String = "Nothing was changed: " + "; ".join(problems)
+		if _redeclares(modifications, declared):
+			refusal += ". modify only adds, so a member the script declares already is changed in the file itself"
+		return _log.failure(refusal)
 	# Each placed line as a zero-based index that moves down whenever a later insertion lands above
 	# it, so the numbers answered are where the lines are in the file written, not where each went
 	# at the moment it was placed.
@@ -259,6 +314,44 @@ static func _header_refusal(named: String, base: String) -> String:
 	return said + "; the nearest %s %s." % ["is" if close.size() == 1 else "are", ", ".join(close)]
 
 
+## Why [param template] cannot be written on [param base], or "". Each template's code calls
+## methods of the class it is written for, so a base outside it makes a script that does not parse.
+## A base whose engine class cannot be read here is left to the engine's parse.
+static func _template_refusal(template: String, base: String, script_path: String) -> String:
+	var wanted: String = str(TEMPLATE_BASES.get(template, ""))
+	var native: String = _engine_class_of(base, script_path)
+	if wanted.is_empty() or native.is_empty():
+		return ""
+	if native == wanted or ClassDB.is_parent_class(native, wanted):
+		return ""
+	var named: String = base if native == base else "%s, a %s," % [base, native]
+	return (
+		(
+			"The %s template is written for a %s, and extends %s is not one. Give extends a %s "
+			+ "class, or leave it out for %s."
+		)
+		% [template, wanted, named, wanted, wanted]
+	)
+
+
+## The engine class [param base] comes down to: itself, the one beneath the script a class_name or
+## a quoted path names, or "" when that script cannot be read.
+static func _engine_class_of(base: String, script_path: String) -> String:
+	if ClassDB.class_exists(base):
+		return base
+	var path: String = ""
+	if base.begins_with('"') or base.begins_with("'"):
+		path = base.substr(1, base.length() - 2)
+		if not path.begins_with("res://") and not path.begins_with("uid://"):
+			path = script_path.get_base_dir().path_join(path)
+	else:
+		path = str(_declared_classes().get(base, ""))
+	if path.is_empty() or not ResourceLoader.exists(path):
+		return ""
+	var script: Script = ResourceLoader.load(path, "Script") as Script
+	return "" if script == null else str(script.get_instance_base_type())
+
+
 # The class_name each script of the project declares, by name, with its path.
 static func _declared_classes() -> Dictionary:
 	var declared: Dictionary = {}
@@ -325,6 +418,15 @@ static func _modification_problems(modifications: Array, declared: Dictionary) -
 	return problems
 
 
+static func _redeclares(modifications: Array, declared: Dictionary) -> bool:
+	for mod: Variant in modifications:
+		if mod is Dictionary:
+			var fields: Dictionary = mod
+			if declared.has(str(fields.get("name", ""))):
+				return true
+	return false
+
+
 # The members [param lines] declares at the top level, by name, as {"kind", "line"} counted from
 # one: variables, constants, signals, functions, enums and inner classes, which share one namespace.
 static func _declared(lines: Array[String]) -> Dictionary:
@@ -472,7 +574,18 @@ func _add_signal(lines: Array[String], mod: Dictionary, placed: Array[Dictionary
 		signal_line += "(" + signal_params + ")"
 
 	var insert_line: int = _signal_insertion_point(lines)
-	return insert_line if _insert(lines, insert_line, [signal_line], placed) else -1
+	# Set apart by a blank line from the header above and from whatever follows that is not a
+	# signal, as the style guide and gdformat lay the signals out.
+	var block: Array[String] = [signal_line]
+	var above: String = lines[insert_line - 1].strip_edges() if insert_line > 0 else ""
+	var at: int = insert_line
+	if not above.is_empty() and not GdhPatterns.without_annotations(above).begins_with("signal "):
+		block.push_front("")
+		at += 1
+	var below: String = lines[insert_line].strip_edges() if insert_line < lines.size() else ""
+	if not below.is_empty() and not GdhPatterns.without_annotations(below).begins_with("signal "):
+		block.append("")
+	return at if _insert(lines, insert_line, block, placed) else -1
 
 
 # Answers with the zero-based index of the `func` line, below the blank lines that separate it.
@@ -545,6 +658,7 @@ func _variable_insertion_point(lines: Array[String]) -> int:
 			before_func = i
 			break
 
+	after_header = _past_class_doc(lines, after_header)
 	for i: int in range(after_header, before_func):
 		if GdhPatterns.without_annotations(lines[i]).begins_with("var "):
 			after_header = i + 1
@@ -552,6 +666,20 @@ func _variable_insertion_point(lines: Array[String]) -> int:
 	return after_header
 
 
+## [param at], or the line after the class's doc comment when [param at] follows the header and
+## one opens there. Godot reads the `##` lines straight below `extends` as the class's own
+## documentation, and a line put between them handed that documentation to the line put there.
+static func _past_class_doc(lines: Array[String], at: int) -> int:
+	if at == 0 or at > lines.size():
+		return at
+	var above: String = GdhPatterns.without_annotations(lines[at - 1])
+	if not (above.begins_with("extends ") or above.begins_with("class_name ")):
+		return at
+	while at < lines.size() and lines[at].strip_edges().begins_with("##"):
+		at += 1
+	return at
+
+
 func _signal_insertion_point(lines: Array[String]) -> int:
 	var after_header: int = 0
 
@@ -566,7 +694,7 @@ func _signal_insertion_point(lines: Array[String]) -> int:
 		elif line.begins_with("var ") or line.begins_with("func "):
 			break
 
-	return after_header
+	return _past_class_doc(lines, after_header)
 
 
 func _function_insertion_point(lines: Array[String], position: String) -> int:
@@ -621,24 +749,15 @@ static func _indentation(line: String) -> String:
 func _script_template(template_name: String) -> String:
 	match template_name:
 		"singleton":
-			return """## Singleton (Autoload) script
-## Add to Project Settings -> Autoload to use as a global singleton
+			return """## One instance for the whole game, which the project makes at start once
+## project_settings add_autoload names it, and every script reaches by that name.
 
-var _instance: Object = null
-
-func _init() -> void:
-\tif _instance != null:
-\t\tpush_error("Singleton instance already exists!")
-\t\treturn
-\t_instance = self
 
 func _ready() -> void:
 \tpass
-
-# Add your singleton methods here
 """
 		"state_machine":
-			return """## Finite State Machine implementation
+			return """## A finite state machine: one state at a time, entered and left through change_state.
 
 signal state_changed(old_state: String, new_state: String)
 
@@ -647,22 +766,27 @@ var current_state: String = ""
 ## physics_process(delta); whichever it has are called.
 var states: Dictionary = {}
 
+
 func _ready() -> void:
 \t_setup_states()
 \tif states.size() > 0:
 \t\tchange_state(str(states.keys()[0]))
 
+
 func _setup_states() -> void:
 \t# Override this to add states
 \t# Example: states["idle"] = IdleState.new()
 \tpass
 
+
 func _process(delta: float) -> void:
 \t_call_state(current_state, "process", [delta])
 
+
 func _physics_process(delta: float) -> void:
 \t_call_state(current_state, "physics_process", [delta])
 
+
 func change_state(new_state: String) -> void:
 \tif not states.has(new_state):
 \t\tpush_error("State not found: " + new_state)
@@ -674,6 +798,7 @@ func change_state(new_state: String) -> void:
 \t_call_state(current_state, "enter", [])
 \tstate_changed.emit(old_state, new_state)
 
+
 ## Calls a method on the named state when it has one; a state without it is left alone.
 func _call_state(state_name: String, method: String, args: Array) -> void:
 \tif state_name.is_empty() or not states.has(state_name):
@@ -683,51 +808,47 @@ func _call_state(state_name: String, method: String, args: Array) -> void:
 \t\tstate.callv(method, args)
 """
 		"component":
-			return """## Component pattern - attach to nodes to add behavior
+			return """## A component: a child node that adds one behaviour to its parent, switched off with disable().
 
 @export var enabled: bool = true
 
+
 func _ready() -> void:
 \tif not enabled:
 \t\tset_process(false)
 \t\tset_physics_process(false)
 
+
 func _process(_delta: float) -> void:
 \tif not enabled:
 \t\treturn
 \t# Component logic here
 \tpass
 
+
 func enable() -> void:
 \tenabled = true
 \tset_process(true)
 \tset_physics_process(true)
 
+
 func disable() -> void:
 \tenabled = false
 \tset_process(false)
 \tset_physics_process(false)
 """
 		"resource":
-			return """## Custom Resource - save and load data
+			return """## Data kept in a .tres file, which resource_edit create makes and the game loads.
 
 @export var id: String = ""
 @export var display_name: String = ""
 @export var description: String = ""
 
+
 func _init(p_id: String = "", p_name: String = "", p_desc: String = "") -> void:
 \tid = p_id
 \tdisplay_name = p_name
 \tdescription = p_desc
-
-func duplicate_resource() -> Resource:
-\tvar new_resource: Resource = duplicate()
-\treturn new_resource
 """
 		_:
-			return """func _ready() -> void:
-\tpass
-
-func _process(_delta: float) -> void:
-\tpass
-"""
+			return ""

package/build/godot/operations/import_pipeline.gd

@@ -224,18 +224,29 @@ func set_import_options(params: Dictionary) -> Dictionary:
 	if not refused.is_empty():
 		return _log.failure("Nothing was written: " + "; ".join(refused))
 
+	# One already holding the value given changes nothing, and listing it as updated said it had.
 	var updated_keys: Array[String] = []
+	var unchanged_keys: Array[String] = []
 	for name: String in fitted_values:
-		config.set_value("params", name, fitted_values[name])
+		var held: Variant = config.get_value("params", name, null)
+		var value: Variant = fitted_values[name]
+		if held != null and typeof(held) == typeof(value) and held == value:
+			unchanged_keys.append(name)
+			continue
+		config.set_value("params", name, value)
 		updated_keys.append(name)
-		_log.debug("Set " + name + " = " + str(fitted_values[name]))
+		_log.debug("Set " + name + " = " + str(value))
 
-	err = config.save(import_file_path)
-	if err != OK:
-		return _log.failure("Failed to save import file: " + str(err))
+	if not updated_keys.is_empty():
+		err = config.save(import_file_path)
+		if err != OK:
+			return _log.failure("Failed to save import file: " + str(err))
 
 	# The reimport that applies them is the server's, through the editor or the engine's import.
-	return {"resource_path": resource_path, "updated_options": updated_keys}
+	var answer: Dictionary = {"resource_path": resource_path, "updated_options": updated_keys}
+	if not unchanged_keys.is_empty():
+		answer["unchanged_options"] = unchanged_keys
+	return answer
 
 
 ## [param given] as the option holds it. Every JSON number arrives as a float, and an enum option

package/build/godot/operations/logger.gd

@@ -6,6 +6,13 @@ extends RefCounted
 # Every module preloads this as `GdhLog`. `Logger` is a native class from Godot 4.5 on, and a
 # constant of that name is a parse error rather than a shadowing warning.
 
+## Printed around engine output an operation provokes to answer a question of its own, such as
+## whether a script parsed before a change, which src/headless.ts leaves out of the answer: its
+## errors are about a file the answer does not describe. Kept in step with `ASIDE` and `RESUMED`
+## there.
+const ASIDE: String = "[gdharness] aside"
+const RESUMED: String = "[gdharness] resumed"
+
 var debug_mode: bool = false
 
 

package/build/godot/operations/property_paths.gd

@@ -0,0 +1,225 @@
+@tool
+extends RefCounted
+
+## Where a property a tool writes lives: on the object given, on a resource built into it, or on an
+## element of one of its lists that the write has to make first.
+
+const GdhRead = preload("reading.gd")
+
+const HEADINGS: int = PROPERTY_USAGE_CATEGORY | PROPERTY_USAGE_GROUP | PROPERTY_USAGE_SUBGROUP
+
+
+## The entry [param target] declares for [param property], or {} when it declares none, headings
+## left out.
+static func declared_on(target: Object, property: String) -> Dictionary:
+	for declared: Dictionary in target.get_property_list():
+		if str(declared.get("name", "")) != property:
+			continue
+		if GdhRead.as_int(declared.get("usage", 0)) & HEADINGS:
+			continue
+		return declared
+	return {}
+
+
+## Where [param key] is written: as [holder, name, through], the object holding the property, its
+## name there, and the resources passed on the way. A key that is none of [param target]'s own may
+## start with the name of one holding a resource built into it, then a slash and a key of that
+## resource: "sources/0/0:0/0/probability" is the probability of tile 0:0 in the atlas source a
+## TileSet keeps as sources/0. A colon path cannot reach it, since the tile's own name holds colons.
+## A resource kept in a file of its own is not reached, nor, given the file [param home] that
+## [param target] is saved in, one built into another file, since writing it here would leave that
+## file as it was.
+static func holder_of(target: Object, key: String, home: String = "") -> Array:
+	var through: Array[Resource] = []
+	var holder: Object = target
+	var name: String = key
+	while declared_on(holder, name).is_empty():
+		var reached: Resource = null
+		var at: int = name.find("/")
+		while at > 0:
+			var held: Resource = built_in_at(holder, name.left(at), home)
+			if held != null:
+				reached = held
+				break
+			at = name.find("/", at + 1)
+		if reached == null:
+			break
+		through.append(reached)
+		holder = reached
+		name = name.substr(at + 1)
+	return [holder, name, through]
+
+
+## The resource [param target] holds under [param property] when it is built into a file, or null;
+## given [param home], only one built into that file or into none yet.
+static func built_in_at(target: Object, property: String, home: String = "") -> Resource:
+	var held: Resource = held_at(target, property)
+	if held == null or not held.is_built_in():
+		return null
+	var file: String = held.resource_path.get_slice("::", 0)
+	return held if home.is_empty() or file.is_empty() or file == home else null
+
+
+## The file [param target] is saved in: its scene's for a node, as the nodes of an instance are
+## saved in the scene holding it, and its own for a resource; "" when it has none yet.
+static func home_of(target: Object) -> String:
+	if target is Node:
+		var top: Node = target
+		while top.owner != null:
+			top = top.owner
+		return top.scene_file_path
+	if target is Resource:
+		var resource: Resource = target
+		return resource.resource_path.get_slice("::", 0)
+	return ""
+
+
+## The resource [param target] holds under [param property], built in or kept in a file, or null.
+static func held_at(target: Object, property: String) -> Resource:
+	if declared_on(target, property).is_empty():
+		return null
+	var held: Variant = target.get(property)
+	return held if held is Resource else null
+
+
+## Makes the element of a list [param name] names on [param target] when it is the next one, as the
+## inspector's Add Element does, and answers "" (also when [param name] is in no list), or why not,
+## [param called] being what [param target] is called. The engine lists an element's properties
+## only once the element exists, so a TileSet with no physics layer had no
+## physics_layer_0/collision_layer to write. A list the engine declares as an array grows through
+## the method named after its elements, add_physics_layer for physics_layer_, given the indices of
+## the lists around it; a list counted by a property, as a tile's polygons are by polygons_count,
+## grows by raising the count.
+static func grow(target: Object, name: String, called: String) -> String:
+	var steps: PackedStringArray = name.split("/")
+	for depth: int in steps.size() - 1:
+		var step: String = steps[depth]
+		var cut: int = step.rfind("_")
+		if cut < 1 or not step.substr(cut + 1).is_valid_int():
+			continue
+		var index: int = step.substr(cut + 1).to_int()
+		var above: String = "/".join(steps.slice(0, depth))
+		var under: String = above + "/" if not above.is_empty() else ""
+		var prefix: String = under + step.left(cut + 1)
+		var element: String = step.left(cut)
+		var counted: String = under + element + "s_count"
+		var count: int = -1
+		var adding: Callable
+		if not declared_on(target, counted).is_empty():
+			count = GdhRead.as_int(target.get(counted))
+			adding = func() -> void: target.set(counted, count + 1)
+		elif _listed_array(target, prefix):
+			count = _elements(target, prefix)
+			var method: String = "add_" + element
+			var outer: Array = []
+			for enclosing: String in steps.slice(0, depth):
+				var at: int = enclosing.rfind("_")
+				if at > 0 and enclosing.substr(at + 1).is_valid_int():
+					outer.append(enclosing.substr(at + 1).to_int())
+			if target.has_method(method):
+				adding = func() -> void: target.callv(method, outer)
+		if count < 0 or index < count:
+			continue
+		var held: String = (
+			"%s has %d %s%s"
+			% [
+				above if not above.is_empty() else called,
+				count,
+				element.replace("_", " "),
+				"" if count == 1 else "s"
+			]
+		)
+		if index > count:
+			return (
+				"%s, and a new one goes after the last, so %s%d cannot be written yet: write %s%d first."
+				% [held, prefix, index, prefix, count]
+			)
+		if not adding.is_valid():
+			return "%s, and nothing makes another, so %s cannot be written." % [held, name]
+		adding.call()
+		return ""
+	return ""
+
+
+## Whether [param target] declares a list whose elements' properties start with [param prefix],
+## as TileSet declares physics_layers for physics_layer_0/collision_layer.
+static func _listed_array(target: Object, prefix: String) -> bool:
+	for declared: Dictionary in target.get_property_list():
+		var usage: int = GdhRead.as_int(declared.get("usage", 0))
+		if usage & PROPERTY_USAGE_ARRAY and str(declared.get("class_name", "")) == prefix:
+			return true
+	return false
+
+
+## How many elements of the list whose properties start with [param prefix] [param target] holds.
+static func _elements(target: Object, prefix: String) -> int:
+	var count: int = 0
+	for declared: Dictionary in target.get_property_list():
+		var name: String = str(declared.get("name", ""))
+		if not name.begins_with(prefix):
+			continue
+		var index: String = name.substr(prefix.length()).get_slice("/", 0)
+		if index.is_valid_int():
+			count = maxi(count, index.to_int() + 1)
+	return count
+
+
+## What [param target] is called in a refusal: the class_name its script declares, or else its
+## engine class. A resource made as a project class is a Resource to the engine, and "Resource.kind"
+## named a property no Resource has.
+static func class_called(target: Object) -> String:
+	var attached: Variant = target.get_script()
+	if attached is Script:
+		var script: Script = attached
+		if not str(script.get_global_name()).is_empty():
+			return str(script.get_global_name())
+	return target.get_class()
+
+
+## The refusal for [param name], which [param target] does not declare, when it runs through a
+## resource saved in a file other than [param home], the one [param target] is saved in; or "". The
+## write belongs in that file, since this one would be saved and that one left as it was: through a
+## TileMapLayer's tile_set kept in a file of its own, or through the mesh of an instance's editable
+## child, which is built into the scene the instance comes from.
+static func held_elsewhere(target: Object, name: String, home: String) -> String:
+	var at: int = name.find("/")
+	while at > 0:
+		var head: String = name.left(at)
+		var rest: String = name.substr(at + 1)
+		var held: Resource = held_at(target, head)
+		var file: String = "" if held == null else held.resource_path.get_slice("::", 0)
+		if held != null and not held.is_built_in():
+			return (
+				"%s.%s is %s, a file of its own, so %s is written there, with resource_edit modify on %s."
+				% [class_called(target), head, file, rest, file]
+			)
+		if held != null and not file.is_empty() and not home.is_empty() and file != home:
+			return _built_in_elsewhere(target, head, rest, held, file)
+		at = name.find("/", at + 1)
+	return ""
+
+
+## The refusal for writing [param rest] into [param held], which [param target] holds under
+## [param head] and which is built into [param file], the scene an instance in this one comes from.
+static func _built_in_elsewhere(
+	target: Object, head: String, rest: String, held: Resource, file: String
+) -> String:
+	var node: String = ""
+	if target is Node:
+		var placed: Node = target
+		var from: Node = placed
+		while from != null and from.scene_file_path != file:
+			from = from.owner
+		if from != null:
+			node = " on %s" % from.get_path_to(placed)
+	var text: String = (
+		(
+			"%s.%s is built into %s, so %s is written there, with scene_node set%s in %s, which changes "
+			+ "it wherever that scene is used. To change it here alone, give %s a %s of its own: a "
+			+ 'value with "_type" set to its class and its properties beside it.'
+		)
+		% [class_called(target), head, file, rest, node, file, head, held.get_class()]
+	)
+	if target is GeometryInstance3D and (held is Material or rest.contains("material")):
+		text += " A material for this instance alone goes in material_override."
+	return text