Add weld-aware validation and map import cleanup

Introduce non-planar face and micro-gap detection in HFValidationSystem, along with configurable weld and planarity tolerances for imported or hand-edited geometry.

Add vertex welding and planarity correction helpers, refresh derived face geometry after weld edits, and harden the spatial-hash implementation with 27-cell neighbor lookup so boundary-straddling pairs are not missed.

Run a post-parse weld pass in MapIO for near-coincident imported .map vertices, add focused GUT coverage for validation, welding, planarity fixes, and MapIO integration, and update project documentation to describe the new behavior and test count.

Author: Shane Wall

CHANGELOG.md

@@ -4,6 +4,46 @@ All notable changes to this project will be documented in this file.
 The format is based on Keep a Changelog, and this project follows semantic versioning.
 
 ## [Unreleased]
+### Added
+- **Map import vertex welding** (Apr 2026): `MapIO.parse_map_text()` now runs a post-parse
+  vertex welding pass on all parsed brush face points before constructing brush geometry.
+  Near-coincident vertices (within `import_weld_tolerance`, default 0.01 units) are averaged
+  to a shared position, closing micro-gaps caused by floating-point representation drift in
+  legacy .map editors. Uses BFS over a spatial hash with 27-cell neighbor lookup so pairs
+  straddling a snap-grid boundary are never missed. The tolerance is configurable via the
+  static `MapIO.import_weld_tolerance` property; set to 0.0 to disable.
+
+- **Non-planar face detection** (Apr 2026): `HFValidationSystem.check_bake_issues()` now
+  flags faces with 4+ vertices where any vertex deviates from the face plane beyond
+  `planarity_tolerance` (default 0.01 units). Reported as `type: "non_planar"`, severity 1.
+  Adjustable per-instance via `val_sys.planarity_tolerance`.
+
+- **Micro-gap detection** (Apr 2026): `check_bake_issues()` now detects near-coincident
+  but not-exactly-equal vertices across different brushes that would cause seam tearing
+  after bake. Reported as `type: "micro_gap"`, severity 1. Tolerance controlled by
+  `val_sys.weld_tolerance` (default 0.001 units).
+
+- **Vertex welding auto-fix** (Apr 2026): `HFValidationSystem.weld_brush_vertices(brush)`
+  snaps all vertices within `weld_tolerance` of each other to their averaged position using
+  BFS grouping over a 27-cell spatial hash. Calls `ensure_geometry()` on every modified face
+  to refresh normals and bounds. Returns the count of welded vertices.
+
+- **Planarity auto-fix** (Apr 2026): `HFValidationSystem.fix_non_planar_faces(brush)`
+  projects drifting vertices back onto the best-fit plane defined by each face's first three
+  vertices. Calls `ensure_geometry()` after correction. Returns the count of vertices fixed.
+
+- **Configurable validation tolerances** (Apr 2026): `HFValidationSystem` gains two public
+  properties — `weld_tolerance` (default 0.001) for vertex coincidence and `planarity_tolerance`
+  (default 0.01) for face-plane deviation. These control the new checks and auto-fix methods.
+  The `_edge_key()` function used by non-manifold/open-edge detection retains its fixed 0.001
+  precision — it is intentionally decoupled from `weld_tolerance` so topology checks remain
+  stable regardless of the weld knob setting.
+
+  21 new tests in `test_weld_and_planarity.gd`: non-planar detection (5), vertex welding (3),
+  planarity fix (3), micro-gap detection (2), edge-key independence (1), boundary-straddling
+  coverage (3), MapIO integration (2), MapIO unit (2).
+  Total: **1299 tests across 73 files**.
+
 ### Changed
 - **Non-blocking face-mode bakes** (Apr 2026): Full bakes using the face-material path
   (`bake_use_face_materials = true`) no longer freeze the editor. The bake system now operates in two

CONTRIBUTING.md

@@ -38,6 +38,7 @@ Thanks for helping improve HammerForge.
 - **Face winding convention**: All faces must use **CW vertex winding** as seen from outside the brush (Godot 4's front-face convention). `_compute_normal()` produces outward normals for CW faces automatically. Never negate normals manually after `ensure_geometry()`. When adding new face generators, verify normals point outward from the brush centroid.
 - **Polygon/path tools** create brushes via `root.brush_system.create_brush_from_info()` with a `faces` key containing serialized face data. Use `FaceData.from_dict()` / `to_dict()` for serialization. Face dicts include `winding_version: 1`; omitting this key triggers load-time migration.
 - **Spawn system** (`root.spawn_system`): use `get_active_spawn()` for primary-flag-aware spawn lookup, `validate_spawn()` for physics-based validation, `auto_fix_spawn()` to apply suggested fixes, `create_default_spawn()` for fallback creation. Quick Play flow calls these automatically. Debug visualisation via `show_validation_debug()` / `cleanup_debug()`. Spawn properties (`primary`, `angle`, `height_offset`) are defined in `entities.json` and auto-generated in the Entities dock.
+- **Validation tolerances**: `HFValidationSystem` has two configurable tolerances — `weld_tolerance` (default 0.001) for vertex coincidence in welding/micro-gap detection, and `planarity_tolerance` (default 0.01) for face-plane deviation. The `_edge_key()` function used by non-manifold/open-edge topology checks uses a **fixed** 0.001 precision and must NOT be coupled to `weld_tolerance` — changing `_edge_key` precision would mask real topology issues when users raise the weld knob. Keep new spatial-hash lookups distance-based with 27-cell neighbor search (see `_cell_keys()`) rather than single-bucket — bucket boundaries silently miss valid pairs. Always call `face.ensure_geometry()` after mutating `local_verts` so normals and bounds stay in sync.
 - **Incremental bake**: `bake_selected()` merges into the existing `baked_container` — never replace the container wholesale. `bake_dirty()` uses `_last_bake_success` to decide whether to clear dirty tags; failed bakes must retain all tags so they can be retried.
 - **Bake preview modes**: use the `PreviewMode` enum (FULL, WIREFRAME, PROXY). Wireframe must use `ShaderMaterial` with `render_mode wireframe` — `StandardMaterial3D` has no `wireframe` property in Godot 4.6.
 - **Quick Play variants**: `_on_quick_play_from_camera()` and `_on_quick_play_selected_area()` must follow the same severity ≥ 2 blocking, auto-create, and fix-dialog patterns as `_on_quick_play()`. Both must restore temporary state (spawn position/angle, cordon) on both success and error paths. Use `_restore_spawn()` helper and explicit type annotations (e.g. `var old_pos: Vector3 =`) to avoid GDScript `:=` inference failures with untyped spawn references.

DEVELOPMENT.md

@@ -95,7 +95,7 @@ addons/hammerforge/
     hf_paint_system.gd     Floor + surface paint, layer CRUD
     hf_state_system.gd     State capture/restore, settings, transactions
     hf_file_system.gd      .hflevel/.map/.glTF I/O, threaded writes, autosave failure reporting
-    hf_validation_system.gd Validation, dependency checks, bake issue detection (degenerate/floating/overlapping)
+    hf_validation_system.gd Validation, dependency checks, bake issue detection (degenerate/floating/overlapping/non-planar/micro-gap), vertex welding + planarity auto-fix
     hf_visgroup_system.gd  Visgroups (visibility groups) + brush/entity grouping
     hf_carve_system.gd     Boolean-subtract carve (progressive-remainder box slicing)
     hf_io_visualizer.gd    Entity I/O connection lines (Bézier curves, color-coded, highlight pulse)
@@ -246,6 +246,7 @@ Tests live in `tests/` and use the [GUT](https://github.com/bitwes/Gut) framewor
 | `test_reference_cleanup.gd` | 9 | Delete cleans group/visgroup membership, entity I/O cleanup_dangling_connections, preserves unrelated, no-crash on clean node |
 | `test_bake_system.gd` | 43 | build_bake_options, structural/trigger filtering, chunk_coord, bake_dry_run, warn_bake_failure, estimate_bake_time, preview mode helpers (+ recursive chunk wireframe/proxy/multimesh/full), _last_bake_success, dirty tag retention, wireframe ShaderMaterial |
 | `test_bake_issues.gd` | 10 | check_bake_issues: degenerate, oversized, floating subtract, overlapping subtracts, non-manifold/open-edge, clean level, entity skip |
+| `test_weld_and_planarity.gd` | 21 | Non-planar face detection (5), vertex welding + ensure_geometry refresh (3), planarity auto-fix (3), micro-gap detection (2), edge-key independence (1), boundary-straddling weld/gap/parse (3), MapIO integration (2), MapIO snap unit (2) |
 | `test_quick_play_modes.gd` | 12 | Severity blocking (0/1/2), cordon save/restore, dirty tag retention patterns, camera yaw via entity_data, spawn restore after camera play, spawn restore on error path |
 | `test_integration.gd` | 22 | End-to-end: brush lifecycle, paint + heightmap, entity workflow, visgroup cross-system, snap, bake cross-system, entity I/O cleanup, brush info round-trip |
 | `test_shortcut_dialog.gd` | 8 | Category assignment (tools, paint, axis lock, editing), action labels (known/unknown), get_all_bindings copy safety |

HammerForge_SPEC.md

@@ -94,7 +94,7 @@ All signals are defined on `LevelRoot`. Subsystems emit them via `root.<signal>.
 | `hf_paint_system.gd` | `HFPaintSystem` | Floor paint input, surface paint, paint layer CRUD, face selection |
 | `hf_state_system.gd` | `HFStateSystem` | State capture/restore, settings, paint layer serialization, transactions (begin/commit/rollback) |
 | `hf_file_system.gd` | `HFFileSystem` | .hflevel save/load, .map import/export, glTF export, threaded I/O, autosave failure reporting |
-| `hf_validation_system.gd` | `HFValidationSystem` | Validation, dependency checks, auto-fix helpers, bake issue detection (degenerate/floating/overlapping) |
+| `hf_validation_system.gd` | `HFValidationSystem` | Validation, dependency checks, auto-fix helpers (vertex weld, planarity fix), bake issue detection (degenerate/floating/overlapping/non-planar/micro-gap). Configurable `weld_tolerance` and `planarity_tolerance`. Edge-key topology hashing intentionally decoupled from weld knob |
 | `hf_visgroup_system.gd` | `HFVisgroupSystem` | Visgroups (visibility groups), brush/entity grouping |
 | `hf_carve_system.gd` | `HFCarveSystem` | Boolean-subtract carve (progressive-remainder box slicing) |
 | `hf_io_visualizer.gd` | `HFIOVisualizer` | Entity I/O connection lines in viewport (ImmediateMesh) |
@@ -326,7 +326,8 @@ Foliage Populator
 - **Bake Changed** (`bake_dirty()`): bakes only brushes with dirty tags (`_dirty_brush_ids`). Tags are cleared only when `_last_bake_success` is true; failed bakes retain all dirty tags.
 - **Preview modes** (`PreviewMode` enum: FULL, WIREFRAME, PROXY): `_apply_preview_visuals()` overrides material on baked meshes. Wireframe uses inline `ShaderMaterial` with `render_mode wireframe`. Proxy uses unshaded semi-transparent `StandardMaterial3D`.
 - **Bake time estimate** (`estimate_bake_time()`): ratio-based extrapolation from `_last_bake_duration_ms` and brush count.
-- **Bake issue detection** (`HFValidationSystem.check_bake_issues()`): returns Array of `{type, severity, message, node}` dicts. Checks: degenerate brush (sev=2), oversized (sev=1), floating subtract (sev=1), overlapping subtracts (sev=1).
+- **Bake issue detection** (`HFValidationSystem.check_bake_issues()`): returns Array of `{type, severity, message, node}` dicts. Checks: degenerate brush (sev=2), oversized (sev=1), floating subtract (sev=1), overlapping subtracts (sev=1), non-manifold edges (sev=2), open edges (sev=1), non-planar faces (sev=1), micro-gaps between brushes (sev=1). Non-planar detection uses `planarity_tolerance` (default 0.01). Micro-gap detection uses `weld_tolerance` (default 0.001). Both use 27-cell spatial hash neighbor lookup for boundary-safe distance checks. `_edge_key()` for topology (non-manifold/open-edge) uses fixed 0.001 precision, intentionally decoupled from `weld_tolerance`.
+- **Auto-fix helpers**: `weld_brush_vertices(brush)` snaps near-coincident vertices within `weld_tolerance` via BFS grouping + `ensure_geometry()` refresh. `fix_non_planar_faces(brush)` projects drifting vertices onto the best-fit plane from each face's first 3 vertices.
 
 ## Face Materials + Surface Paint
 Face data is stored per DraftBrush face with material assignment, UV projection, and optional paint layers.
@@ -479,6 +480,7 @@ Unit tests use the [GUT](https://github.com/bitwes/Gut) framework and run headle
 | `test_reference_cleanup.gd` | 9 | Delete cleans group/visgroup membership, entity I/O cleanup_dangling_connections |
 | `test_bake_system.gd` | 38 | build_bake_options, structural/trigger filtering, chunk_coord, bake_dry_run, warn_bake_failure, estimate_bake_time, preview modes, _last_bake_success, dirty tag retention, wireframe ShaderMaterial |
 | `test_bake_issues.gd` | 10 | check_bake_issues: degenerate, oversized, floating subtract, overlapping subtracts, clean level, entity skip |
+| `test_weld_and_planarity.gd` | 21 | Non-planar detection, vertex welding + ensure_geometry refresh, planarity auto-fix, micro-gap detection, edge-key independence, boundary-straddling coverage, MapIO integration + unit |
 | `test_quick_play_modes.gd` | 12 | Severity blocking (0/1/2), cordon save/restore, dirty tag retention, camera yaw via entity_data, spawn restore |
 | `test_integration.gd` | 22 | End-to-end: brush lifecycle, paint + heightmap, entity workflow, visgroup cross-system, snap, bake, I/O cleanup, info round-trip |
 | `test_shortcut_dialog.gd` | 8 | Category assignment (tools, paint, axis lock, editing), action labels, get_all_bindings copy safety |

README.md

@@ -9,7 +9,7 @@
   <img src="https://img.shields.io/badge/Godot-4.6%2B-478cbf?logo=godot-engine&logoColor=white" alt="Godot 4.6+">
   <img src="https://img.shields.io/badge/License-MIT-green" alt="MIT License">
   <img src="https://img.shields.io/badge/Status-Early%20Alpha-red" alt="Early Alpha">
-  <img src="https://img.shields.io/badge/Tests-1278%20passing-brightgreen" alt="1270 tests passing">
+  <img src="https://img.shields.io/badge/Tests-1299%20passing-brightgreen" alt="1299 tests passing">
   <img src="https://img.shields.io/badge/GDScript-25k%2B%20lines-blueviolet" alt="25k+ lines">
 </p>
 
@@ -40,7 +40,7 @@ HammerForge is a single `addons/` folder. No external tools, no custom builds, n
 
 | | |
 |---|---|
-| **21 subsystems** + coordinator architecture | **1278 unit + integration tests** with CI on every push |
+| **21 subsystems** + coordinator architecture | **1299 unit + integration tests** with CI on every push |
 | **15 brush shapes** (box through dodecahedron) | **150 built-in prototype textures** for instant greyboxing |
 | **Quake `.map`** + **glTF `.glb`** export | **.hflevel** native format with threaded I/O |
 | **Customizable keymaps** (JSON) | **Plugin API** for custom tools |
@@ -180,7 +180,7 @@ Grid-based paint layers with chunked storage for large worlds:
 | **Material Atlas** | Pack albedo textures into a single atlas to reduce draw calls (face materials mode) |
 | **Bake Visible Only** | Skip hidden visgroups and invisible brushes |
 | **Unwrap UV0** | Per-vertex planar UV projection for surfaces without UVs |
-| **Check Issues** | Flag degenerate, floating, overlapping, non-manifold, and open-edge brushes |
+| **Check Issues** | Flag degenerate, floating, overlapping, non-manifold, open-edge, non-planar, and micro-gap brushes. Auto-fix: vertex weld + planarity correction |
 | **Bake estimate** | Time estimate with "Chunking recommended" tip for large levels |
 | **Validate** | Check level integrity before bake |
 | **.map export** | Classic Quake or Valve 220 format |
@@ -445,5 +445,5 @@ Run `godot --headless --import --path .` first, then re-run the test command.
 
 <p align="center">
   <strong>MIT License</strong><br>
-  <sub>Built for Godot 4.6+ | Last updated April 5, 2026</sub>
+  <sub>Built for Godot 4.6+ | Last updated April 9, 2026</sub>
 </p>

addons/hammerforge/map_io.gd

@@ -11,6 +11,11 @@ const HFMapQuakeType = preload("map_adapters/hf_map_quake.gd")
 const DEFAULT_TEXTURE := "__default"
 const AXIS_THRESHOLD := 0.98
 
+## Vertex snapping tolerance for imported .map geometry.  Vertices closer than
+## this distance are welded to their average position to eliminate floating-point
+## drift from legacy editors.  Set to 0.0 to disable.
+static var import_weld_tolerance: float = 0.01
+
 
 static func load_map(path: String) -> Dictionary:
 	if path == "" or not FileAccess.file_exists(path):
@@ -70,6 +75,12 @@ static func parse_map_text(text: String) -> Dictionary:
 			if kv.size() == 2:
 				current_entity["properties"][kv[0]] = kv[1]
 			continue
+	# Weld near-coincident vertices across all parsed faces to close micro-gaps
+	if import_weld_tolerance > 0.0:
+		for entity in entities:
+			for brush in entity.get("brushes", []):
+				_snap_parsed_vertices(brush.get("faces", []), import_weld_tolerance)
+
 	var brushes: Array = []
 	var entity_points: Array = []
 	for entity in entities:
@@ -354,3 +365,85 @@ static func _format_vec3(v: Vector3) -> String:
 
 static func _snapped(value: float) -> String:
 	return String.num(value, 3)
+
+
+## Snap near-coincident vertices within a single parsed brush's face list.
+## Uses BFS over a spatial hash with 27-cell neighbor lookup so pairs straddling
+## a bucket boundary are never missed.  Averages each cluster and writes
+## the canonical position back.
+static func _snap_parsed_vertices(faces: Array, tolerance: float) -> void:
+	if tolerance <= 0.0:
+		return
+	# Collect all vertex references into a flat list + spatial hash
+	var entries: Array = []  # Array of {fi: int, pi: int, pos: Vector3}
+	var cells: Dictionary = {}  # cell_key -> Array[int]
+	for fi in range(faces.size()):
+		var points: Array = faces[fi].get("points", [])
+		for pi in range(points.size()):
+			var idx: int = entries.size()
+			var pos: Vector3 = points[pi]
+			entries.append({"fi": fi, "pi": pi, "pos": pos})
+			var key: String = _snap_cell_key(pos, tolerance)
+			if not cells.has(key):
+				cells[key] = []
+			(cells[key] as Array).append(idx)
+	# BFS grouping
+	var group_of: PackedInt32Array = PackedInt32Array()
+	group_of.resize(entries.size())
+	group_of.fill(-1)
+	var groups: Array = []  # Array of Array[int]
+	for seed_idx in range(entries.size()):
+		if group_of[seed_idx] >= 0:
+			continue
+		var gid: int = groups.size()
+		var members: Array = [seed_idx]
+		group_of[seed_idx] = gid
+		var queue: Array = [seed_idx]
+		while not queue.is_empty():
+			var cur: int = queue.pop_front()
+			var cur_pos: Vector3 = entries[cur]["pos"]
+			for cell_key: String in _snap_cell_keys(cur_pos, tolerance):
+				for neighbor_idx: int in cells.get(cell_key, []):
+					if group_of[neighbor_idx] >= 0:
+						continue
+					if cur_pos.distance_to(entries[neighbor_idx]["pos"]) <= tolerance:
+						group_of[neighbor_idx] = gid
+						members.append(neighbor_idx)
+						queue.append(neighbor_idx)
+		groups.append(members)
+	# Average each group and write back
+	for members: Array in groups:
+		if members.size() < 2:
+			continue
+		var avg := Vector3.ZERO
+		for idx: int in members:
+			avg += entries[idx]["pos"]
+		avg /= float(members.size())
+		var any_moved := false
+		for idx: int in members:
+			if (entries[idx]["pos"] as Vector3).distance_to(avg) > 0.0:
+				any_moved = true
+				break
+		if not any_moved:
+			continue
+		for idx: int in members:
+			var fi: int = entries[idx]["fi"]
+			var pi: int = entries[idx]["pi"]
+			faces[fi]["points"][pi] = avg
+
+
+static func _snap_cell_key(v: Vector3, tol: float) -> String:
+	return "%s,%s,%s" % [snapped(v.x, tol), snapped(v.y, tol), snapped(v.z, tol)]
+
+
+## Return all 27 cell keys (self + 26 neighbors) for spatial hash lookup.
+static func _snap_cell_keys(v: Vector3, cell_size: float) -> Array:
+	var cx: float = snapped(v.x, cell_size)
+	var cy: float = snapped(v.y, cell_size)
+	var cz: float = snapped(v.z, cell_size)
+	var keys: Array = []
+	for dx in [-cell_size, 0.0, cell_size]:
+		for dy in [-cell_size, 0.0, cell_size]:
+			for dz in [-cell_size, 0.0, cell_size]:
+				keys.append("%s,%s,%s" % [cx + dx, cy + dy, cz + dz])
+	return keys