b3dCloneEntityMaterial

Explicitly clones entity's material for independent modification (prevents shared material issues). Takes entityHandle (mesh entity handle). Returns nothing. Calls EnsureUniqueMaterial helper to clone mesh and material if shared by multiple entities, allowing safe texture/property modification without affecting other entities. Mesh entities only.

This function ensures material independence. Clone mechanism: checks if entity.mesh is shared by multiple entities (counts references in g_entities), if shared (refCount > 1) creates shallow mesh copy with new cloned material (GPU buffers shared via ComPtr, only mesh struct and material cloned), updates entity to use new independent mesh, if not shared (refCount = 1) no-op (already unique). Material cloning: copies material from g_materials[mesh->materialIndex], appends to g_materials vector as new entry, updates new mesh to use new material index. Mesh cloning: shallow copy of GPU resources (vertexBuffer, indexBuffer shared via ComPtr, no GPU memory duplication), copies metadata (vertexCount, indexCount, transformIndex, boundingBox, boundingRadius), only mesh struct itself is duplicated. Use cases: (1) Texture swapping (clone then b3dSetEntityBaseTexture without affecting other instances), (2) Per-instance materials (same GLB model different textures per entity), (3) Material property changes (modify metallic/roughness on single instance), (4) Decal application (add texture to one entity without affecting others), (5) Dynamic material changes (runtime texture/property updates per entity). Common patterns: clone before texture change b3dCloneEntityMaterial(entity) then b3dSetEntityBaseTexture(entity, newTexture), clone for team colors b3dCloneEntityMaterial(player) then b3dSetEntityColorFX(player, teamRed, teamGreen, teamBlue), clone for damage states b3dCloneEntityMaterial(vehicle) then b3dSetEntityBaseTexture(vehicle, damagedTexture). Typical usage: call before modifying textures if entity shares mesh with others (prevents unexpected side effects), use for instanced objects that need per-instance appearance (characters, vehicles, pickups), call once per entity that needs independent material (subsequent material changes affect only this entity). Shared mesh detection: automatically detects if mesh is shared by counting entities with same mesh pointer (if entity A and B both use mesh X, cloning A's material creates new mesh Y for A, B still uses X). GPU resource sharing: cloned meshes share GPU vertex/index buffers (no GPU memory cost, only CPU struct overhead), uses ComPtr reference counting for safe sharing. Performance: O(N) where N = entity count (iterates all entities to count references), cloning itself is O(1) (shallow copy, material vector append), only clones if necessary (refCount > 1). When to use: call before first material/texture modification if entity might be instanced, not needed for procedural shapes (they use surface-based materials), essential for loaded GLB models (they share meshes via g_meshCache). Automatic cloning: SetEntityColorFX and similar functions use entity.materialOverrideIndex system (different approach, stores override index in entity instead of cloning mesh), b3dCloneEntityMaterial is explicit mesh-level clone (for texture changes that require mesh.materialIndex modification). GLB instancing: loaded GLB models cached in g_meshCache (multiple entities share same mesh pointer), modifying mesh->materialIndex affects all instances unless cloned first. Default behavior: without cloning texture/material changes to one entity affect all entities sharing the mesh (unexpected side effect), cloning ensures changes are per-entity. Validation: prints error if invalid entity handle, prints error if entity is not mesh type or has no mesh, silently returns if entity already has unique mesh (refCount = 1). Related: b3dSetEntityBaseTexture sets base color texture (requires clone for instanced meshes), b3dSetEntityColorFX sets color via materialOverrideIndex (alternative per-entity customization), b3dLoadEntity loads GLB models (creates shared meshes).