b3dCopyMesh

Creates a deep copy of a mesh entity with independent vertex/index buffers. Takes sourceHandle (mesh entity to copy). Returns new mesh entity handle or 0 on failure. Validates source exists and type is ENTITY_MESH (not ENTITY_ANIMATED_MESH - those more complex). Validates mesh data exists. Gets 3D device. Allocates new Mesh3D structure. Deep copies all mesh data: vertices array (full copy), indices array (full copy), vertexCount, indexCount, triangleCount, boundingRadius, materialIndex, submeshes, maxDetailSlots, allowsUVTransforms. Copies surface-based mesh data (surfaces array, isSurfaceBased flag, needsGPUUpload, locked). Deep copies material: clones material from g_materials, adds to array, assigns new index. For multi-material meshes, clones all submesh materials. For surface-based meshes, clones all surface materials. Allocates GPU resources: creates new vertex buffer (D3D12_HEAP_TYPE_DEFAULT), creates new index buffer, uploads via intermediate UPLOAD buffer, transitions to VERTEX_AND_CONSTANT_BUFFER / INDEX_BUFFER state. Creates new entity with copied mesh. Sets entity position (0,0,0), rotation (0,0,0), scale (1,1,1). Returns entity handle. Returns 0 if: invalid source, source not ENTITY_MESH, no mesh data, GPU allocation fails, device not initialized.

This function creates fully independent mesh copies for per-instance vertex editing. Deep copy means new GPU buffers allocated - each copy consumes VRAM equal to original. Expensive operation (memory allocation, GPU upload, command list execution). Use when: (1) Vertex deformation needed (bent trees, damaged vehicles), (2) Procedural geometry modification (random rocks), (3) Destructible environments (per-copy bullet holes), (4) Texture atlas variations (different UV coordinates per copy). Memory cost: mesh with 10K vertices, 4 bytes * 10 attributes * 10K = 400KB per copy. 100 copies = 40MB VRAM. Compare to b3dCopyEntity which shares mesh (100 copies = 400KB total). GPU upload blocks command queue - avoid during gameplay, prefer loading screens. Material deep copy enables per-copy colors/textures without affecting original. Surface-based meshes (b3dCreateMesh): fully copyable, supports b3dAddMeshVertex modifications. Loaded meshes (b3dLoadMesh): copyable but vertex data not modifiable via BambooBasic API (would need b3dUpdateMeshVertices if exposed). After copy, use b3dLockMesh / vertex editing functions to modify geometry. New entity has default transform (0,0,0) - use b3dSetPosition afterwards. Hierarchy not copied - no parent/children. Use b3dCopyEntity for instancing (shared mesh), b3dCopyMesh for unique geometry. Common workflow: base = b3dLoadMesh("tree.glb"), deformed = b3dCopyMesh(base), b3dLockMesh(deformed), modify vertices, b3dUnlockMesh(deformed).