gdharness 1.3.1 → 1.3.2

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

@@ -252,7 +252,7 @@ func create_resource(args: Dictionary) -> Dictionary:
 	if not folder.is_empty():
 		return {"ok": false, "error": folder}
 	var answer: Dictionary = {"ok": true, "resourcePath": res_path, "resourceType": asked_type}
-	_properties.note_also_changed(answer)
+	_properties.note_write(answer)
 	var failed: String = _save_checked(resource, res_path, properties.keys(), null)
 	if not failed.is_empty():
 		return {"ok": false, "error": failed}
@@ -290,7 +290,7 @@ func modify_resource(args: Dictionary) -> Dictionary:
 	if not refused.is_empty():
 		return {"ok": false, "error": refused}
 	var answer: Dictionary = {"ok": true, "resourcePath": res_path}
-	_properties.note_also_changed(answer)
+	_properties.note_write(answer)
 	var previous: PackedByteArray = FileAccess.get_file_as_bytes(res_path)
 	var failed: String = _save_checked(resource, res_path, properties.keys(), previous)
 	if not failed.is_empty():
@@ -346,7 +346,19 @@ func create_tileset(args: Dictionary) -> Dictionary:
 	var tileset_path: String = _ensure_res_path(str(args.get("resourcePath", "")))
 	if tileset_path == "res://":
 		return {"ok": false, "error": "resourcePath is required"}
-	var taken: String = _taken(tileset_path, "resource_edit op=create_tileset")
+	# modify sets properties and builds no atlas, so the other path is the only way on offered.
+	var taken: String = (
+		""
+		if not FileAccess.file_exists(tileset_path)
+		else (
+			(
+				"%s already exists, and create_tileset builds a whole new TileSet, which would replace "
+				+ "everything in it, the tiles a scene paints with among them. Give resourcePath a path "
+				+ "nothing is at."
+			)
+			% tileset_path
+		)
+	)
 	if not taken.is_empty():
 		return {"ok": false, "error": taken}
 
@@ -374,9 +386,16 @@ func create_tileset(args: Dictionary) -> Dictionary:
 				"ok": false,
 				"error": "The TileSet did not take the atlas for %s" % atlas.texture.resource_path
 			}
-		made.append(
-			{"sourceId": added, "texture": atlas.texture.resource_path, "tiles": atlas.get_tiles_count()}
-		)
+		var entry: Dictionary = {
+			"sourceId": added, "texture": atlas.texture.resource_path, "tiles": atlas.get_tiles_count()
+		}
+		var blank: Array = built[2]
+		if not blank.is_empty():
+			entry["leftBlank"] = blank
+		var spare: String = built[3]
+		if not spare.is_empty():
+			entry["notInAnyTile"] = spare
+		made.append(entry)
 
 	var folder: String = GdhSceneFile.make_folder_for(tileset_path)
 	if not folder.is_empty():
@@ -389,11 +408,14 @@ func create_tileset(args: Dictionary) -> Dictionary:
 	return {"ok": true, "tilesetPath": tileset_path, "sources": made}
 
 
-## One atlas source from its description, with its tiles made, as [true, source] or [false, why].
+## One atlas source from its description, with its tiles made, as [true, source, the grid cells left
+## without a tile for being wholly transparent, a sentence on the pixels no tile covers or ""] or
+## [false, why].
 ##
 ## Tiles are made in every cell of the grid that has a pixel that is not transparent, which is
 ## what the editor offers to do when an atlas gets a texture. Without them the atlas held no tiles,
-## and every cell painted from it drew nothing.
+## and every cell painted from it drew nothing. The cells passed over and the strip a tile size that
+## does not divide the picture leaves are said, since a count alone left a caller to work out which.
 func _atlas(entry: Variant, index: int) -> Array:
 	if not entry is Dictionary:
 		return [false, "sources[%d] must be an object with texture and tileSize" % index]
@@ -455,6 +477,7 @@ func _atlas(entry: Variant, index: int) -> Array:
 			)
 		]
 	var image: Image = texture.get_image()
+	var blank: Array = []
 	for y: int in grid.y:
 		for x: int in grid.x:
 			var cell: Vector2i = Vector2i(x, y)
@@ -464,9 +487,33 @@ func _atlas(entry: Variant, index: int) -> Array:
 				atlas.texture_region_size
 			)
 			if image != null and _blank(image, region):
+				blank.append({"x": x, "y": y})
 				continue
 			atlas.create_tile(cell)
-	return [true, atlas]
+	var covered: Vector2i = atlas.margins + grid * tile_size + (grid - Vector2i.ONE) * atlas.separation
+	var left: Vector2i = Vector2i(texture.get_size()) - covered
+	var sides: PackedStringArray = []
+	if left.x > 0:
+		var _right: bool = sides.append("%d px on the right" % left.x)
+	if left.y > 0:
+		var _bottom: bool = sides.append("%d px at the bottom" % left.y)
+	var spare: String = (
+		""
+		if sides.is_empty()
+		else (
+			"%s is %d by %d, so %s %s in no %d by %d tile."
+			% [
+				texture_path,
+				texture.get_width(),
+				texture.get_height(),
+				" and ".join(sides),
+				"is" if sides.size() == 1 else "are",
+				tile_size.x,
+				tile_size.y
+			]
+		)
+	)
+	return [true, atlas, blank, spare]
 
 
 func _blank(image: Image, region: Rect2i) -> bool:
@@ -475,12 +522,15 @@ func _blank(image: Image, region: Rect2i) -> bool:
 	return image.get_region(region).is_invisible()
 
 
-## The source ids a tile set holds, for saying what a cell could have named instead.
-func _source_ids(tile_set: TileSet) -> Array[int]:
-	var ids: Array[int] = []
+## The sources a tile set holds, as "source 0", "sources 0, 2" or "no sources", for saying what a
+## cell could have named instead.
+func _sources_of(tile_set: TileSet) -> String:
+	var ids: PackedStringArray = []
 	for index: int in tile_set.get_source_count():
-		ids.append(tile_set.get_source_id(index))
-	return ids
+		var _listed: bool = ids.append(str(tile_set.get_source_id(index)))
+	if ids.is_empty():
+		return "no sources"
+	return ("source " if ids.size() == 1 else "sources ") + ", ".join(ids)
 
 
 func set_tilemap_cells(args: Dictionary) -> Dictionary:
@@ -517,11 +567,20 @@ func set_tilemap_cells(args: Dictionary) -> Dictionary:
 	var tile_set: TileSet = layered.tile_set if layered != null else single.tile_set
 
 	scene.asked(node, ["layer_%d/tile_data" % layer if layered != null else "tile_map_data"])
-	var wanted: Array = []
+	# Every cell is checked before any is placed, and every one refused is named: stopping at the first
+	# left a caller fixing one cell a call.
+	var checked: Array = []
+	var refusals: PackedStringArray = []
 	for index: int in placed.size():
 		var cell: Array = _cell(placed[index], index, tile_set)
 		if not cell[0]:
-			return scene.refuse(str(cell[1]))
+			var _named: bool = refusals.append(str(cell[1]))
+		checked.append(cell)
+	if not refusals.is_empty():
+		return scene.refuse("%s. Nothing was placed." % "; ".join(refusals))
+	var wanted: Array = []
+	var erased: int = 0
+	for cell: Array in checked:
 		var at: Vector2i = cell[1]
 		var source_id: int = cell[2]
 		var atlas_coords: Vector2i = cell[3]
@@ -531,6 +590,8 @@ func set_tilemap_cells(args: Dictionary) -> Dictionary:
 		else:
 			single.set_cell(at, source_id, atlas_coords, alternative)
 		wanted.append([at, source_id, atlas_coords, alternative])
+		if source_id == -1:
+			erased += 1
 
 	var at_path: String = scene.path_of(node)
 	var written: Dictionary = scene.write(
@@ -546,7 +607,13 @@ func set_tilemap_cells(args: Dictionary) -> Dictionary:
 	if not written.is_empty():
 		return written
 
-	return {"ok": true, "layer": layer, "placed": wanted.size(), "requested": placed.size()}
+	return {
+		"ok": true,
+		"layer": layer,
+		"placed": wanted.size() - erased,
+		"erased": erased,
+		"requested": placed.size()
+	}
 
 
 ## The node at [param node_path] cells are painted on, with a TileSet, as [node, why not].
@@ -575,40 +642,55 @@ func _tile_node(scene: GdhSceneFile, node_path: String, layer: int) -> Array:
 
 
 ## One cell from its description, checked against [param tile_set], as
-## [true, coords, source id, atlas coords, alternative] or [false, why].
+## [true, coords, source id, atlas coords, alternative] or [false, why]. A source of -1 erases the
+## cell, as set_cell takes it, and needs no atlasCoords.
 func _cell(entry: Variant, index: int, tile_set: TileSet) -> Array:
 	if not entry is Dictionary:
 		return [false, "cells[%d] must be an object with coords, sourceId and atlasCoords" % index]
 	var cell: Dictionary = entry
-	for field: String in ["coords", "sourceId", "atlasCoords"]:
+	for field: String in ["coords", "sourceId"]:
 		if not cell.has(field):
 			return [false, "cells[%d] has no %s" % [index, field]]
 	var at: Array = _xy(cell["coords"], "cells[%d].coords" % index)
 	if not at[0]:
 		return at
+	var coords: Vector2i = at[1]
+	var named: String = "cells[%d] at (%d, %d)" % [index, coords.x, coords.y]
+	var source_id: int = GdhRead.as_int(cell["sourceId"], -2)
+	if source_id == -1:
+		return [true, coords, -1, Vector2i(-1, -1), -1]
+	if not cell.has("atlasCoords"):
+		return [
+			false, "%s has no atlasCoords, which every cell but an erased one (sourceId -1) needs" % named
+		]
 	var atlas_at: Array = _xy(cell["atlasCoords"], "cells[%d].atlasCoords" % index)
 	if not atlas_at[0]:
 		return atlas_at
-	var source_id: int = GdhRead.as_int(cell["sourceId"], -1)
 	if not tile_set.has_source(source_id):
-		return [false, "The TileSet has no source %d; it has %s" % [source_id, _source_ids(tile_set)]]
+		return [
+			false,
+			(
+				"%s names source %d, and the TileSet has %s; sourceId -1 erases a cell"
+				% [named, source_id, _sources_of(tile_set)]
+			)
+		]
 	var source: TileSetSource = tile_set.get_source(source_id)
 	var atlas_coords: Vector2i = atlas_at[1]
 	var alternative: int = GdhRead.as_int(cell.get("alternativeTile", 0))
 	if not source.has_tile(atlas_coords):
 		return [
 			false,
-			(
-				"cells[%d]: source %d has no tile at %s; it has %s. Nothing was placed."
-				% [index, source_id, atlas_coords, _tiles_of(source)]
-			)
+			"%s: source %d has no tile at %s; it has %s" % [named, source_id, atlas_coords, _tiles_of(source)]
 		]
 	if not source.has_alternative_tile(atlas_coords, alternative):
 		return [
 			false,
-			"The tile at %s in source %d has no alternative %d" % [atlas_coords, source_id, alternative]
+			(
+				"%s: the tile at %s in source %d has no alternative %d"
+				% [named, atlas_coords, source_id, alternative]
+			)
 		]
-	return [true, at[1], source_id, atlas_coords, alternative]
+	return [true, coords, source_id, atlas_coords, alternative]
 
 
 ## The atlas coordinates [param source] has tiles at, the first twelve and how many more, or that it
@@ -722,13 +804,12 @@ func set_theme_color(args: Dictionary) -> Dictionary:
 	if theme == null:
 		return {"ok": false, "error": "No Theme at %s. Create one there first." % theme_path}
 
-	var c: Dictionary = args.get("color", {})
-	var color: Color = Color(
-		GdhRead.as_float(c.get("r", 1.0), 1.0),
-		GdhRead.as_float(c.get("g", 1.0), 1.0),
-		GdhRead.as_float(c.get("b", 1.0), 1.0),
-		GdhRead.as_float(c.get("a", 1.0), 1.0)
-	)
+	# Read as a property write reads a colour, html code included, so a value scene_node takes for a
+	# Button's modulate is taken for its theme colour too; "#ff8000" was refused here alone.
+	var parsed: Array = _properties.colour_from(args.get("color", {}), "color")
+	if not parsed[0]:
+		return {"ok": false, "error": parsed[1]}
+	var color: Color = parsed[1]
 	theme.set_color(color_name, control_type, color)
 
 	var unsaved: String = _save_theme(theme, theme_path, "%s/colors/%s" % [control_type, color_name])
@@ -768,17 +849,18 @@ func set_theme_font_size(args: Dictionary) -> Dictionary:
 	# Godot reads a size of 0 or less as unset and answers the theme's default, so -3 would be read
 	# back as 16.
 	var pixels: float = GdhRead.as_float(args.get("size"), 0.0)
-	if not is_finite(pixels) or pixels < 1 or pixels != floorf(pixels):
-		var shown: String = str(int(pixels)) if pixels == floorf(pixels) else str(pixels)
+	if not is_finite(pixels) or pixels != floorf(pixels):
+		return {"ok": false, "error": "size is a whole number of pixels, and %s is not one." % str(pixels)}
+	if pixels < 1:
 		return {
 			"ok": false,
 			"error":
 			(
 				(
-					"size must be a whole number of pixels, 1 or more, not %s: Godot reads 0 or less as no size "
-					% shown
+					"size must be 1 or more, not %d: the theme would hold it, and Godot reads a size of 0 or "
+					+ "less as unset and draws the default size instead."
 				)
-				+ "and uses the theme's default instead."
+				% int(pixels)
 			)
 		}
 	theme.set_font_size(font_size_name, control_type, int(pixels))
@@ -819,4 +901,16 @@ func _noting_variation(answer: Dictionary) -> Dictionary:
 		)
 		% [type, type]
 	)
+	# A variation is any name, so a misspelt class is written all the same, and the classes nearest
+	# it are what tells a caller which one was meant.
+	var themed: PackedStringArray = []
+	for known: String in ClassDB.get_class_list():
+		if ClassDB.is_parent_class(known, "Control") or ClassDB.is_parent_class(known, "Window"):
+			var _added: bool = themed.append(known)
+	var close: PackedStringArray = GdhRead.nearest(type, themed)
+	if not close.is_empty():
+		answer["note"] += (
+			" If a class was meant, the nearest %s %s."
+			% ["is" if close.size() == 1 else "are", ", ".join(close)]
+		)
 	return answer

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

@@ -60,17 +60,15 @@ func _find_node(root: Node, path: String) -> Node:
 ## Why the property or signal [param missing] could not be found on [param node], adding the one
 ## cause the name alone does not show: a script that does not compile leaves the editor holding a
 ## placeholder with no properties or signals at all, and the refusal named the property instead.
+## Such a script has no engine class beneath it. Compiling a copy of the source to find out failed on
+## every script with a class_name, since the copy hides the global class the original declares.
 func _missing_on(node: Node, missing: String) -> String:
 	var script: Script = node.get_script()
-	if script == null or not script.has_source_code():
-		return missing
-	var probe: GDScript = GDScript.new()
-	probe.source_code = script.source_code
-	if probe.reload() == OK:
+	if script == null or not str(script.get_instance_base_type()).is_empty():
 		return missing
 	return (
 		"%s. Its script, %s, does not compile, so none of what it declares is known here."
-		% [missing, script.resource_path]
+		% [missing.trim_suffix("."), script.resource_path]
 	)
 
 
@@ -343,7 +341,7 @@ func add_node(args: Dictionary) -> Dictionary:
 		"nodePath": new_path,
 		"index": new_node.get_index(),
 	}
-	_properties.note_also_changed(answer, new_node)
+	_properties.note_write(answer, new_node)
 	var written: Dictionary = scene.write(
 		func(saved: Node) -> String:
 			return _kept(
@@ -608,7 +606,7 @@ func set_node_properties(args: Dictionary) -> Dictionary:
 		held[str(key)] = _readable(node, _properties.read_at(node, str(key)))
 	var new_path: String = scene.path_of(node)
 	var answer: Dictionary = {"ok": true, "nodePath": new_path, "properties": held}
-	_properties.note_also_changed(answer, node)
+	_properties.note_write(answer, node)
 	var carried: GdhPaths = GdhPaths.new()
 	var _rewritten: int = carried.carry(scene, {old_path: new_path} if new_path != old_path else {})
 	var written: Dictionary = scene.write(
@@ -848,7 +846,8 @@ func _connection_ends(
 		if not foreign.is_empty():
 			return [null, foreign]
 	if not source.has_signal(signal_name):
-		return [null, _missing_on(source, "%s has no signal %s" % [source_node_path, signal_name])]
+		var said: String = "%s has no signal %s" % [source_node_path, signal_name]
+		return [null, _missing_on(source, GdhRead.offered(said, signal_name, GdhRead.signals_of(source)))]
 	return [source, target]
 
 
@@ -920,6 +919,7 @@ func disconnect_signal(args: Dictionary) -> Dictionary:
 
 	return {
 		"ok": true,
+		"removed": true,
 		"sourceNodePath": from,
 		"signalName": signal_name,
 		"targetNodePath": to,

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

@@ -82,6 +82,13 @@ static func spare(fields: Dictionary, tag: String) -> Array:
 ##
 ## The refusal names only the two types, and the key is what the caller has to take out.
 static func remedy(value: Variant, type: int) -> String:
+	if type == TYPE_STRING and typeof(value) in [TYPE_BOOL, TYPE_INT, TYPE_FLOAT]:
+		var number: Variant = value
+		if value is float:
+			var whole: float = value
+			if is_finite(whole) and whole == floorf(whole):
+				number = int(whole)
+		return ' Text is sent in quotes, as "%s".' % str(number)
 	var shape: String = written_as(type)
 	if shape.is_empty():
 		return ""

package/build/godot/addons/gdharness_runtime/reading.gd

@@ -164,6 +164,43 @@ static func not_of_kind(
 	return told + " The scene's %ss are at %s." % [kind, shown]
 
 
+## Up to three of [param names] closest to [param word], closest first, ignoring case: the names a
+## refusal offers for one that is not there, as a typo usually is one of them.
+static func nearest(word: String, names: PackedStringArray) -> PackedStringArray:
+	var wanted: String = word.to_lower()
+	var close: Array[String] = []
+	for name: String in names:
+		if name.to_lower().similarity(wanted) >= 0.5:
+			close.append(name)
+	close.sort_custom(
+		func(a: String, b: String) -> bool:
+			return a.to_lower().similarity(wanted) > b.to_lower().similarity(wanted)
+	)
+	return PackedStringArray(close.slice(0, 3))
+
+
+## [param said], the refusal for [param word], which is not among [param names], with those nearest
+## it when any are, or else every one of them, so the caller has a name to send instead.
+static func offered(said: String, word: String, names: Array) -> String:
+	var every: PackedStringArray = PackedStringArray(names)
+	var close: PackedStringArray = nearest(word, every)
+	if close.is_empty():
+		return "%s; it has %s" % [said, ", ".join(every)]
+	return "%s; the nearest it has %s %s" % [said, "is" if close.size() == 1 else "are", ", ".join(close)]
+
+
+## The signals [param object] has that a caller can connect, its own class's first: the engine
+## lists them from Object down, which puts a Button's pressed after thirty a Control has, and names
+## starting with an underscore are the engine's own.
+static func signals_of(object: Object) -> Array:
+	var names: Array = []
+	for entry: Dictionary in object.get_signal_list():
+		var name: String = str(entry["name"])
+		if not name.begins_with("_"):
+			names.push_front(name)
+	return names
+
+
 ## [param word] after the article it takes, "an AnimationTree" or "a Node2D".
 static func with_article(word: String) -> String:
 	return ("an " if word.left(1).to_upper() in ["A", "E", "I", "O", "U"] else "a ") + word

package/build/godot/addons/gdharness_runtime/runtime_values.gd

@@ -71,10 +71,36 @@ static func node_at(root: Node, path: String) -> Dictionary:
 
 	var node: Node = root.get_node_or_null(path)
 	if node == null:
-		return {"type": "error", "message": "Node not found: " + path}
+		return {"type": "error", "message": _not_found(root, path)}
 	return {"node": node}
 
 
+## "Node not found" for [param path], with the deepest node of it the game has and the children that
+## node has instead, as a scene's refusal names them: a mistyped step was otherwise found by reading
+## the whole tree.
+static func _not_found(root: Node, path: String) -> String:
+	var said: String = "Node not found: " + path
+	var parts: PackedStringArray = path.split("/", false)
+	var at: Node = root
+	var step: int = 0
+	if path.begins_with("/"):
+		if parts.is_empty() or parts[0] != str(root.name):
+			return said
+		step = 1
+	while step < parts.size():
+		var below: Node = at.get_node_or_null(NodePath(parts[step]))
+		if below == null:
+			break
+		at = below
+		step += 1
+	if step >= parts.size():
+		return said
+	var names: PackedStringArray = []
+	for child: Node in at.get_children():
+		var _named: bool = names.append(str(child.name))
+	return GdhRead.missing_below(said, "", PackedStringArray([str(at.get_path())]), parts[step], names)
+
+
 ## How many process frames a whole press holds before its release, from `holdFrames`: one unless
 ## asked, as the halves of a press have always been a frame apart. Held inside the game because the
 ## time between a press, a wait and a release sent as three calls counts as held too: a 60-frame

package/build/godot/addons/gdharness_runtime/serialisation.gd

@@ -410,6 +410,10 @@ func fitted(value: Variant, type: int) -> Variant:
 	var simple: Array[int] = [TYPE_BOOL, TYPE_INT, TYPE_FLOAT, TYPE_STRING]
 	if not simple.has(type) or not simple.has(typeof(rebuilt)):
 		return rebuilt
+	# A number or a truth value stays as sent where text is wanted, for the refusal to name. Converted,
+	# 1 arrived as the double it is in JSON and was saved as "1.0", which is not the text anyone sends.
+	if type == TYPE_STRING and not rebuilt is String:
+		return rebuilt
 
 	# Digits are read as digits, since read as JSON they become a double and one past 2^53 a
 	# neighbour of the number written.

package/build/godot/addons/gdharness_runtime/value_shapes.gd

@@ -82,6 +82,13 @@ static func spare(fields: Dictionary, tag: String) -> Array:
 ##
 ## The refusal names only the two types, and the key is what the caller has to take out.
 static func remedy(value: Variant, type: int) -> String:
+	if type == TYPE_STRING and typeof(value) in [TYPE_BOOL, TYPE_INT, TYPE_FLOAT]:
+		var number: Variant = value
+		if value is float:
+			var whole: float = value
+			if is_finite(whole) and whole == floorf(whole):
+				number = int(whole)
+		return ' Text is sent in quotes, as "%s".' % str(number)
 	var shape: String = written_as(type)
 	if shape.is_empty():
 		return ""

package/build/godot/operations/classdb_queries.gd

@@ -183,13 +183,23 @@ func _not_found(wanted: String) -> Dictionary:
 					)
 				)
 			)
+	# The usual miss is a spelling, one letter off a class the engine has.
+	var close: PackedStringArray = GdhRead.nearest(wanted, ClassDB.get_class_list())
+	var offered: String = (
+		""
+		if close.is_empty()
+		else (
+			" The nearest engine %s %s."
+			% ["class is" if close.size() == 1 else "classes are", ", ".join(close)]
+		)
+	)
 	return _log.failure(
 		(
 			(
-				"Class not found: %s. editor_classes reads the engine's ClassDB, so a class_name a project "
-				+ "script declares is not in it either; script_info structure reads one."
+				"Class not found: %s.%s editor_classes reads the engine's ClassDB, so a class_name a "
+				+ "project script declares is not in it either; script_info structure reads one."
 			)
-			% wanted
+			% [wanted, offered]
 		)
 	)
 

package/build/godot/operations/declared_values.gd

@@ -0,0 +1,116 @@
+@tool
+extends RefCounted
+
+## What a property declares beyond its type: the values of its enum and the range it is exported
+## with, for taking a value by name and for saying when a value written lies outside them.
+
+const GdhRead = preload("reading.gd")
+
+
+## The values an enum hint names, by name, from its hint string: "SWORD:0,SHIELD:1" as a script
+## declares one, or "Add,Subtract" as an engine property does, each name then taking the number
+## after the one before it.
+static func enum_values(hint_string: String) -> Dictionary:
+	var values: Dictionary = {}
+	var next: int = 0
+	for entry: String in hint_string.split(",", false):
+		var name: String = entry.get_slice(":", 0).strip_edges()
+		var number: String = entry.get_slice(":", 1).strip_edges() if ":" in entry else ""
+		var value: int = number.to_int() if number.is_valid_int() else next
+		values[name] = value
+		next = value + 1
+	return values
+
+
+## The values of the enum [param declared] declares, by name, spelt as the script of [param target]
+## spells them when it declares that enum. The engine's hint capitalises each name, "SWORD" as
+## "Sword", and a refusal listing those named values the script never spells.
+static func enum_of(target: Object, declared: Dictionary) -> Dictionary:
+	var hinted: Dictionary = enum_values(str(declared.get("hint_string", "")))
+	var attached: Variant = target.get_script()
+	if not attached is Script:
+		return hinted
+	var script: Script = attached
+	for constant: Variant in script.get_script_constant_map().values():
+		if not constant is Dictionary:
+			continue
+		var values: Dictionary = constant
+		if values.size() != hinted.size():
+			continue
+		var spelt: Dictionary = {}
+		for name: Variant in values:
+			if hinted.get(str(name).capitalize()) == values[name]:
+				spelt[str(name)] = values[name]
+		if spelt.size() == hinted.size():
+			return spelt
+	return hinted
+
+
+## The number [param word] names among [param choices], matched as written and then ignoring case,
+## or null when it names none.
+static func enum_named(choices: Dictionary, word: String) -> Variant:
+	var wanted: String = word.strip_edges()
+	if choices.has(wanted):
+		return choices[wanted]
+	for name: String in choices:
+		if name.to_lower() == wanted.to_lower():
+			return choices[name]
+	return null
+
+
+static func enum_refusal(holder: String, property: String, word: String, choices: Dictionary) -> String:
+	var said: String = (
+		"%s.%s is an enum, and %s is none of its values: send %s by name or by number"
+		% [holder, property, word, _listed(choices)]
+	)
+	var close: PackedStringArray = GdhRead.nearest(word, PackedStringArray(choices.keys()))
+	if close.is_empty():
+		return said + "."
+	return said + ". The nearest %s %s." % ["is" if close.size() == 1 else "are", ", ".join(close)]
+
+
+## Why [param value], shown as [param shown], lies outside what [param declared] allows, an export
+## range or an enum's values, or "" when it does not. A range marked or_greater or or_less is open
+## on that side.
+static func outside(target: Object, declared: Dictionary, value: Variant, shown: String) -> String:
+	var hint: int = GdhRead.as_int(declared.get("hint", PROPERTY_HINT_NONE))
+	var hint_string: String = str(declared.get("hint_string", ""))
+	var property: String = str(declared.get("name", ""))
+	if typeof(value) != TYPE_INT and typeof(value) != TYPE_FLOAT:
+		return ""
+	var number: float = GdhRead.as_float(value)
+	if hint == PROPERTY_HINT_ENUM and typeof(value) == TYPE_INT:
+		var choices: Dictionary = enum_of(target, declared)
+		if choices.is_empty() or choices.values().has(value):
+			return ""
+		return "%d is none of the values %s declares: %s." % [value, property, _listed(choices)]
+	if hint != PROPERTY_HINT_RANGE:
+		return ""
+	var parts: PackedStringArray = []
+	for part: String in hint_string.split(","):
+		var _added: bool = parts.append(part.strip_edges())
+	if parts.size() < 2 or not parts[0].is_valid_float() or not parts[1].is_valid_float():
+		return ""
+	var low: float = parts[0].to_float()
+	var high: float = parts[1].to_float()
+	if (number <= high or parts.has("or_greater")) and (number >= low or parts.has("or_less")):
+		return ""
+	return (
+		(
+			"%s is outside the range %s declares, %s to %s, which the inspector holds it to; the "
+			+ "engine stores it as given."
+		)
+		% [shown, property, _bound(low), _bound(high)]
+	)
+
+
+static func _listed(choices: Dictionary) -> String:
+	var listed: PackedStringArray = []
+	for name: String in choices:
+		var _added: bool = listed.append("%s (%d)" % [name, choices[name]])
+	return ", ".join(listed)
+
+
+## A range's end as the script wrote it: the engine's hint gives @export_range(0, 10) as 0.0 and 10.0.
+static func _bound(end: float) -> String:
+	return str(int(end)) if end == floorf(end) and absf(end) < 1e15 else str(end)