Merges source mesh geometry into destination mesh (combines vertices/indices, multi-material support). Takes sourceMesh (source entity handle), destMesh (destination entity handle). Returns nothing. Validates both entities exist and are mesh type, calls EnsureUniqueMesh on destination (copy-on-write), appends all source vertices to destination, appends all source indices offset by original vertex count, handles multi-material rendering via submeshes (creates submeshes if materials differ, keeps single-material if same), clears material overrides, handles locked meshes (defers GPU upload), unlocked meshes immediately rebuild buffers. Permanent geometry modification of destination.
This function combines meshes into single entity. Mesh merging workflow: (1) Validate source and destination are mesh entities, (2) EnsureUniqueMesh on destination (prevents shared mesh corruption), (3) Record original vertex/index counts, (4) Append source vertices to destination (no modifications, copied as-is), (5) Append source indices with offset (sourceIndex + originalVertexCount for correct vertex references), (6) Handle material assignments (single-material or multi-material via submeshes), (7) Rebuild GPU buffers if unlocked. Use cases: (1) Combine multiple meshes for batching (reduce draw calls), (2) Procedural mesh construction (build complex shapes from primitives), (3) Level assembly (merge room sections), (4) Performance optimization (static batching), (5) Mesh welding (combine separate parts). Material handling: checks destination and source material indices (respects materialOverrideIndex if set, otherwise uses mesh->materialIndex), if materials match: keeps single-material mode (submeshes.clear(), all geometry uses same material), if materials differ: creates submeshes for multi-material rendering (destSubmesh for original geometry with original material, sourceSubmesh for added geometry with source material). Submesh system: like GLB multi-material support, each submesh has indexStart, indexCount, materialIndex, enables single mesh with multiple materials (different sections rendered with different materials). Material override clearing: if destination had materialOverrideIndex, moves it to mesh->materialIndex and clears override (submesh-based materials used instead of entity-level override). Vertex appending: copies all source vertices unchanged: for each sourceVertex: destMesh->vertices.push_back(sourceVertex), preserves position/normal/tangent/UV/color data. Index offsetting: source indices reference source vertices (0-based in source mesh), destination indices must reference correct vertices in combined mesh: destMesh->indices.push_back(sourceIndex + originalVertexCount), offsets ensure indices point to newly added vertices. Empty source: if source mesh has no vertices, function returns early (nothing to add, destination unchanged). Copy-on-write: EnsureUniqueMesh ensures destination mesh is unique (creates copy if shared by multiple entities), prevents corruption of other entities using same mesh. Lock/unlock pattern: if destMesh->locked==true, sets needsGPUUpload=true, defers buffer rebuild (for batch operations), if unlocked: immediately calls RebuildGPUBuffersFromSurfaces, uploads to GPU. Performance: O(N + M) where N=source vertex count, M=source index count, vertex/index copying is memory copy (fast), submesh creation is O(1), GPU upload expensive if unlocked (defer with lock/unlock for multiple AddMesh calls). Typical usage: mesh1=b3dLoadMesh("part1.glb"), mesh2=b3dLoadMesh("part2.glb"), b3dAddMesh(mesh2, mesh1) merges part2 into part1, or b3dLockMesh(dest), b3dAddMesh(source1, dest), b3dAddMesh(source2, dest), b3dUnlockMesh(dest) for multiple merges. Coordinate space: operates in mesh local space (source and destination assumed in same coordinate system), if meshes have different entity transforms, use b3dPositionMesh/RotateMesh/ScaleMesh to align before merging. Hierarchy: merged geometry added to destination entity only, source entity unchanged (remains separate entity, can be hidden/deleted after merge). Related: EnsureUniqueMesh handles copy-on-write, b3dLockMesh/UnlockMesh for batch operations, RebuildGPUBuffersFromSurfaces uploads to GPU, b3dLoadMesh loads meshes for merging, submesh system for multi-material rendering.