Improve texture workflow feedback and tooltip guidance

Expand texture and material tooltips so the dock exposes the actual workflow: prototype loading, face selection prerequisites, brush-vs-face material behavior, bake material usage, terrain slot blending, UV reset guidance, and texture lock scope.

Teach material thumbnail tooltips about hover preview, double-click apply, and right-click actions to make the browser more discoverable.

Harden material assignment feedback by validating face selections against real brushes and face bounds, preventing misleading counts, and resolving whole-brush assignments through _find_brush_by_key so unsaved brushes with instance-id fallback are handled correctly.

Clean up noisy GUT output by normalizing JSON number assertions in HFLevelIO tests and deleting test brushes immediately in reference cleanup tests to avoid transient orphans during test execution.

Validation run:

- gdformat --check addons/hammerforge/

- gdlint addons/hammerforge/

- Godot 4.6.1 headless import

- GUT headless suite: 694/694 passing

Author: Shane Wall

addons/hammerforge/dock.gd

@@ -868,12 +868,24 @@ func _apply_all_tooltips() -> void:
 	_set_tooltip(sides_spin, "Side count for polygon shapes (Pyramid, Prism)")
 	_set_tooltip(commit_freeze, "Keep committed cuts frozen (restorable)\ninstead of deleting them")
 	_set_tooltip(collision_layer_opt, "Physics collision layer for baked geometry")
-	_set_tooltip(active_material_button, "Active material for Select+Paint brush painting")
+	_set_tooltip(
+		active_material_button,
+		(
+			"Brush-level material override for whole brushes"
+			+ "\nThis is separate from per-face materials in the Materials tab"
+		)
+	)
 	# Build tab - Bake options
 	_set_tooltip(bake_merge_meshes, "Merge meshes during bake for better performance")
 	_set_tooltip(bake_generate_lods, "Generate LOD meshes during bake")
 	_set_tooltip(bake_lightmap_uv2, "Generate UV2 for lightmap baking")
-	_set_tooltip(bake_use_face_materials, "Apply per-face materials from the Materials tab")
+	_set_tooltip(
+		bake_use_face_materials,
+		(
+			"Bake per-face materials into the final mesh"
+			+ "\nTurn off to ignore face assignments and use brush-level materials instead"
+		)
+	)
 	_set_tooltip(bake_navmesh, "Generate navigation mesh during bake")
 	_set_tooltip(bake_lightmap_texel, "Lightmap texel density (smaller = higher quality)")
 	_set_tooltip(bake_navmesh_cell_size, "Navigation mesh cell size (XZ)")
@@ -902,13 +914,25 @@ func _apply_all_tooltips() -> void:
 	_set_tooltip(layer_y_spin, "Vertical Y offset for the active paint layer")
 	_set_tooltip(blend_strength_spin, "Blend strength when using the Blend paint tool")
 	_set_tooltip(blend_slot_select, "Blend target slot (B, C, or D)")
-	_set_tooltip(terrain_slot_a_button, "Texture for Slot A (base)")
+	_set_tooltip(
+		terrain_slot_a_button,
+		"Choose terrain texture for Slot A (base layer)\nBlend between slots with the Blend paint tool"
+	)
 	_set_tooltip(terrain_slot_a_scale, "UV scale for Slot A texture")
-	_set_tooltip(terrain_slot_b_button, "Texture for Slot B")
+	_set_tooltip(
+		terrain_slot_b_button,
+		"Choose terrain texture for Slot B\nBlend between slots with the Blend paint tool"
+	)
 	_set_tooltip(terrain_slot_b_scale, "UV scale for Slot B texture")
-	_set_tooltip(terrain_slot_c_button, "Texture for Slot C")
+	_set_tooltip(
+		terrain_slot_c_button,
+		"Choose terrain texture for Slot C\nBlend between slots with the Blend paint tool"
+	)
 	_set_tooltip(terrain_slot_c_scale, "UV scale for Slot C texture")
-	_set_tooltip(terrain_slot_d_button, "Texture for Slot D")
+	_set_tooltip(
+		terrain_slot_d_button,
+		"Choose terrain texture for Slot D\nBlend between slots with the Blend paint tool"
+	)
 	_set_tooltip(terrain_slot_d_scale, "UV scale for Slot D texture")
 	# SurfacePaint tab
 	_set_tooltip(paint_target_select, "Paint target: Floor (grid) or Surface (UV)")
@@ -917,21 +941,48 @@ func _apply_all_tooltips() -> void:
 	_set_tooltip(surface_paint_layer_select, "Active surface paint layer")
 	_set_tooltip(surface_paint_layer_add, "Add a new surface paint layer")
 	_set_tooltip(surface_paint_layer_remove, "Remove the selected surface paint layer")
-	_set_tooltip(surface_paint_texture, "Texture for the selected surface paint layer")
+	_set_tooltip(
+		surface_paint_texture,
+		(
+			"Choose the texture for the selected surface-paint layer"
+			+ "\nRequires a selected face and an existing paint layer"
+		)
+	)
 	# Materials tab
 	_set_tooltip(
 		face_select_mode,
-		"Enable per-face selection for material assignment\nClick faces in viewport to select them"
+		(
+			"Enable per-face texturing"
+			+ "\nClick faces in the viewport to select them"
+			+ "\nShift+Click adds more faces"
+			+ "\nRequired for per-face assign, UV edit, and surface paint"
+		)
 	)
 	_set_tooltip(material_add, "Add a material to the palette")
 	_set_tooltip(material_remove, "Remove selected material from palette")
 	_set_tooltip(
-		material_load_prototypes, "Refresh all built-in prototype textures into the palette"
+		material_load_prototypes,
+		(
+			"Load built-in prototype textures into the palette"
+			+ "\nUse this first if the browser looks empty"
+		)
+	)
+	_set_tooltip(
+		material_assign,
+		(
+			"Apply the selected material to all selected faces"
+			+ "\nTip: choose a texture in the browser, then click faces in Face Select Mode"
+		)
 	)
-	_set_tooltip(material_assign, "Assign selected material to selected faces")
 	_set_tooltip(face_clear, "Clear face selection")
 	# UV tab
-	_set_tooltip(uv_reset, "Reset UV coordinates to defaults for selected face")
+	_set_tooltip(
+		uv_reset,
+		(
+			"Reset this face to default projected UVs"
+			+ "\nUse after stretching or before Fit/Center/Left/Right justify"
+		)
+	)
 	# Manage tab
 	_set_tooltip(floor_btn, "Create a default floor brush")
 	_set_tooltip(apply_cuts_btn, "Move pending cuts into the draft brush tree")
@@ -3663,9 +3714,44 @@ func _on_material_assign() -> void:
 		return
 	if not level_root:
 		return
+	var face_count := _count_selected_faces()
+	if face_count == 0:
+		show_toast("No faces selected — select faces first", 1)
+		return
 	_commit_state_action(
 		"Assign Face Material", "assign_material_to_selected_faces", [_selected_material_index]
 	)
+	var mat_name := _material_display_name(_selected_material_index)
+	show_toast(
+		"Applied %s to %d face%s" % [mat_name, face_count, "" if face_count == 1 else "s"], 0
+	)
+
+
+func _count_selected_faces() -> int:
+	if not level_root:
+		return 0
+	var total := 0
+	for key in level_root.face_selection.keys():
+		var brush = level_root._find_brush_by_key(str(key))
+		if not brush:
+			continue
+		var indices: Array = level_root.face_selection.get(key, [])
+		for idx in indices:
+			if int(idx) >= 0 and int(idx) < brush.faces.size():
+				total += 1
+	return total
+
+
+func _material_display_name(index: int) -> String:
+	if not level_root or not level_root.material_manager:
+		return "material"
+	var mat = level_root.material_manager.get_material(index)
+	if mat == null:
+		return "material"
+	var name: String = (
+		mat.resource_name if mat.resource_name != "" else mat.resource_path.get_file()
+	)
+	return name if name != "" else "material"
 
 
 func _on_face_clear() -> void:
@@ -3690,7 +3776,15 @@ func _on_browser_material_double_clicked(index: int) -> void:
 		material_browser.set_selected_index(index)
 	# Double-click triggers immediate face assignment.
 	if level_root and index >= 0:
+		var face_count := _count_selected_faces()
+		if face_count == 0:
+			show_toast("No faces selected — select faces first", 1)
+			return
 		_commit_state_action("Assign Face Material", "assign_material_to_selected_faces", [index])
+		var mat_name := _material_display_name(index)
+		show_toast(
+			"Applied %s to %d face%s" % [mat_name, face_count, "" if face_count == 1 else "s"], 0
+		)
 
 
 func _on_browser_context_menu(index: int, global_pos: Vector2) -> void:
@@ -3711,19 +3805,34 @@ func _on_material_context_action(id: int) -> void:
 	var idx = _material_context_index
 	if idx < 0:
 		return
+	var mat_name := _material_display_name(idx)
 	match id:
 		0:  # Apply to Selected Faces
 			_selected_material_index = idx
+			var face_count := _count_selected_faces()
+			if face_count == 0:
+				show_toast("No faces selected — select faces first", 1)
+				return
 			_commit_state_action("Assign Face Material", "assign_material_to_selected_faces", [idx])
+			show_toast(
+				"Applied %s to %d face%s" % [mat_name, face_count, "" if face_count == 1 else "s"],
+				0
+			)
 		1:  # Apply to Whole Brush — assign material to ALL faces on selected brushes
 			_selected_material_index = idx
-			if _selection_nodes.is_empty():
+			var brush_ids := _get_selected_brush_ids()
+			if brush_ids.is_empty():
 				show_toast("No brushes selected", 1)
 				return
 			_commit_state_action(
-				"Assign Brush Material",
-				"assign_material_to_whole_brushes",
-				[idx, _get_selected_brush_ids()]
+				"Assign Brush Material", "assign_material_to_whole_brushes", [idx, brush_ids]
+			)
+			show_toast(
+				(
+					"Applied %s to %d brush%s"
+					% [mat_name, brush_ids.size(), "" if brush_ids.size() == 1 else "es"]
+				),
+				0
 			)
 		2:  # Toggle Favorite
 			if material_browser:
@@ -4832,7 +4941,7 @@ func _setup_texture_lock_ui() -> void:
 	texture_lock_check = CheckBox.new()
 	texture_lock_check.text = "Texture Lock"
 	texture_lock_check.button_pressed = true
-	texture_lock_check.tooltip_text = "Preserve UV alignment when moving or resizing brushes"
+	texture_lock_check.tooltip_text = "Keep texture alignment while moving, resizing, hollowing, or clipping brushes"
 	texture_lock_check.toggled.connect(_on_texture_lock_toggled)
 	brush_vbox.add_child(texture_lock_check)
 

addons/hammerforge/level_root.gd

@@ -1108,8 +1108,8 @@ func get_primary_selected_face() -> Dictionary:
 	return brush_system.get_primary_selected_face()
 
 
-func assign_material_to_selected_faces(material_index: int) -> void:
-	brush_system.assign_material_to_selected_faces(material_index)
+func assign_material_to_selected_faces(material_index: int) -> int:
+	return brush_system.assign_material_to_selected_faces(material_index)
 
 
 func assign_material_to_faces_by_id(
@@ -1124,15 +1124,18 @@ func assign_material_to_faces_by_id(
 	brush.assign_material_to_faces(material_index, typed_indices)
 
 
-func assign_material_to_whole_brushes(material_index: int, brush_ids: Array) -> void:
+func assign_material_to_whole_brushes(material_index: int, brush_ids: Array) -> int:
+	var count := 0
 	for bid in brush_ids:
-		var brush: DraftBrush = brush_system.find_brush_by_id(str(bid))
+		var brush: DraftBrush = brush_system._find_brush_by_key(str(bid))
 		if not brush or not is_instance_valid(brush):
 			continue
 		var all_indices: Array[int] = []
 		for i in range(brush.faces.size()):
 			all_indices.append(i)
 		brush.assign_material_to_faces(material_index, all_indices)
+		count += all_indices.size()
+	return count
 
 
 func _apply_face_selection() -> void:

addons/hammerforge/systems/hf_brush_system.gd

@@ -764,7 +764,8 @@ func get_primary_selected_face() -> Dictionary:
 	return {}
 
 
-func assign_material_to_selected_faces(material_index: int) -> void:
+func assign_material_to_selected_faces(material_index: int) -> int:
+	var count := 0
 	for key in root.face_selection.keys():
 		var brush = _find_brush_by_key(str(key))
 		if not brush:
@@ -774,6 +775,8 @@ func assign_material_to_selected_faces(material_index: int) -> void:
 		for idx in indices:
 			typed.append(int(idx))
 		brush.assign_material_to_faces(material_index, typed)
+		count += typed.size()
+	return count
 
 
 func _apply_face_selection() -> void:

addons/hammerforge/systems/hf_paint_system.gd

@@ -300,7 +300,8 @@ func get_primary_selected_face() -> Dictionary:
 	return {}
 
 
-func assign_material_to_selected_faces(material_index: int) -> void:
+func assign_material_to_selected_faces(material_index: int) -> int:
+	var count := 0
 	for key in root.face_selection.keys():
 		var brush = root._find_brush_by_key(str(key))
 		if not brush:
@@ -310,6 +311,8 @@ func assign_material_to_selected_faces(material_index: int) -> void:
 		for idx in indices:
 			typed.append(int(idx))
 		brush.assign_material_to_faces(material_index, typed)
+		count += typed.size()
+	return count
 
 
 func apply_face_selection() -> void:

addons/hammerforge/ui/hf_material_browser.gd

@@ -263,9 +263,16 @@ func _create_thumb_button(palette_index: int, mat: Material, mat_path: String) -
 	container.add_child(label)
 
 	# Tooltip
-	container.tooltip_text = _get_material_label(mat)
+	var tip := _get_material_label(mat)
 	if _favorites.has(mat_path):
-		container.tooltip_text += " [Favorite]"
+		tip += " [Favorite]"
+	tip += (
+		"\n\nLeft-click: Select material"
+		+ "\nHover: Preview on selected faces"
+		+ "\nDouble-click: Apply to selected faces"
+		+ "\nRight-click: Apply to whole brush, favorite, copy name"
+	)
+	container.tooltip_text = tip
 
 	# Wrap in a button-like panel for click/hover
 	var btn = Button.new()

tests/test_hflevel_io.gd

@@ -289,7 +289,7 @@ func test_build_parse_complex_payload():
 	}
 	var payload = HFLevelIO.build_payload(data)
 	var parsed = HFLevelIO.parse_payload(payload)
-	assert_eq(parsed.get("version"), 2)
+	assert_eq(int(parsed.get("version", 0)), 2)
 	var brushes = parsed.get("brushes", [])
 	assert_eq(brushes.size(), 2, "Brushes array preserved")
 	assert_eq(brushes[0].get("id"), "brush_1")
@@ -318,4 +318,4 @@ func test_full_pipeline_round_trip():
 	assert_almost_eq(decoded["scale"].y, 3.0, 0.001, "Full pipeline: scale.y")
 	assert_true(decoded["color"] is Color, "Full pipeline: Color survives")
 	assert_eq(decoded["name"], "level_1", "Full pipeline: string survives")
-	assert_eq(decoded["count"], 42, "Full pipeline: int survives")
+	assert_eq(int(decoded["count"]), 42, "Full pipeline: integer value survives")

tests/test_reference_cleanup.gd

@@ -116,6 +116,12 @@ func _make_entity(entity_name: String) -> DraftEntity:
 	return e
 
 
+func _delete_brush_now(brush: DraftBrush) -> void:
+	brush_sys.delete_brush(brush, false)
+	if is_instance_valid(brush):
+		brush.free()
+
+
 # ===========================================================================
 # Group cleanup
 # ===========================================================================
@@ -125,15 +131,15 @@ func test_delete_brush_cleans_group_membership():
 	var b = _make_brush(Vector3.ZERO, Vector3(32, 32, 32), "g1")
 	visgroup_sys.group_selection("mygroup", [b])
 	assert_eq(visgroup_sys.get_group_members("mygroup").size(), 1)
-	brush_sys.delete_brush(b)
+	_delete_brush_now(b)
 	assert_eq(visgroup_sys.get_group_members("mygroup").size(), 0)
 
 
 func test_delete_brush_cleans_empty_group():
 	var b = _make_brush(Vector3.ZERO, Vector3(32, 32, 32), "g2")
 	visgroup_sys.group_selection("tempgroup", [b])
 	assert_true(visgroup_sys.groups.has("tempgroup"))
-	brush_sys.delete_brush(b)
+	_delete_brush_now(b)
 	assert_false(visgroup_sys.groups.has("tempgroup"), "Empty group should be removed")
 
 
@@ -147,7 +153,7 @@ func test_delete_brush_clears_visgroup_meta():
 	visgroup_sys.create_visgroup("lights")
 	visgroup_sys.add_to_visgroup(b, "lights")
 	assert_eq(visgroup_sys.get_members_of("lights").size(), 1)
-	brush_sys.delete_brush(b)
+	_delete_brush_now(b)
 	# After deletion, the visgroup should have no members
 	assert_eq(visgroup_sys.get_members_of("lights").size(), 0)
 
@@ -197,6 +203,6 @@ func test_cleanup_no_connections_returns_zero():
 
 func test_delete_with_no_references_no_crash():
 	var b = _make_brush(Vector3.ZERO, Vector3(32, 32, 32), "plain")
-	brush_sys.delete_brush(b)
+	_delete_brush_now(b)
 	# No crash, no error — just works
 	assert_true(true)