b3dWeldVertices

Merges duplicate vertices within threshold distance using spatial hashing. Takes mesh (surface-based mesh entity), threshold (distance tolerance as double, typically 0.0001 to 0.1). Returns nothing. Validates mesh exists, type is ENTITY_MESH, surface-based, and locked. Processes each surface independently. Builds spatial hash (grid structure, cell size = threshold) mapping 3D grid cells to vertex indices. Creates remap table (old vertex index -> new vertex index). For each vertex, searches cell and 26 neighboring cells for duplicates within threshold distance. When duplicate found, remaps both to same vertex (keeps first, discards rest). Updates all indices in surface to reference remapped vertices. Compacts vertex array removing unused vertices. Rebuilds indices to match new vertex array. Tracks total welded count. Silently returns on errors.

This function optimizes mesh by removing duplicate vertices from modeling software exports or procedural generation. Spatial hashing enables O(N) performance instead of O(N^2) brute-force - grid subdivides space into cells, only checks nearby vertices. Threshold parameter: larger = more aggressive merging (may over-weld distinct vertices), smaller = conservative (may miss near-duplicates). Typical values: 0.0001 for precision modeling, 0.01 for game assets, 0.1 for rough approximation. Use cases: (1) Clean up OBJ imports (exporters often duplicate vertices unnecessarily), (2) Optimize procedural meshes (surface stitching creates duplicate boundary vertices), (3) Fix modeling errors (artists accidentally create overlapping vertices), (4) Reduce vertex count for rendering (fewer vertices = better performance). Welding merges position, normal, UV, color - all attributes must match (within threshold for position). Vertex compaction: after remapping, removes unused vertices from array, rebuilds index buffer to reference compacted array. Index buffer update preserves triangle winding. Must lock mesh before calling. After welding, unlock to upload changes. Surface independence: each surface welded separately, vertices not shared across surfaces (could create cross-surface welds if needed with global remapping). 26-neighbor search covers all adjacent cells (3x3x3 cube minus center). Common pattern: Import OBJ (1000 verts), weld (reduces to 600 verts), performance improved. Grid Key uses int coordinates (floor(position/cellSize)) for hashing. Alternative: pre-weld during mesh creation by detecting duplicates before adding vertices.