b3dGetEntityMetallicFX

Returns entity metallic PBR property (0.0-1.0 double). Takes entity (mesh entity handle, positive integer). Returns double metallic value (0.0=non-metallic/dielectric to 1.0=fully metallic, -1.0 on error). Queries metallic property from entity material for physically-based rendering, checks material override first then base material.

Metallic meaning: 0.0=dielectric materials (wood, plastic, stone, leather, fabric - non-conductors), 0.5=partially metallic (uncommon, usually avoid intermediate values), 1.0=metallic materials (iron, steel, gold, silver, copper, aluminum - conductors). Affects reflection behavior (dielectrics have colored diffuse + white specular, metals have no diffuse + colored specular based on baseColor).

Material source: checks entity.materialOverrideIndex first (if >= 0 uses per-entity override material), falls back to entity.mesh->materialIndex (shared mesh material), reads material.metallicFactor field.

PBR rendering impact: metallic=0.0 uses baseColor for diffuse reflection (colored surface with white highlights), metallic=1.0 uses baseColor for specular reflection (colored metallic reflections, no diffuse), intermediate values blend between behaviors (though physically binary in real world), combines with roughness for surface appearance (smooth metal=shiny, rough metal=brushed).

Use cases: (1) Query material type (If b3dGetEntityMetallicFX(entity%)<0.5 Then dielectric Else metal), (2) Material restoration (save metallic before modification, restore later), (3) Material validation (check if entity configured as metal or dielectric), (4) Dynamic material changes (read current metallic, interpolate to target), (5) Visual effects (query metallic for shader parameter adjustments).

Common patterns: save metallic = oldMetallic#=b3dGetEntityMetallicFX(entity%); check material type = If b3dGetEntityMetallicFX(entity%)>0.5 Then metallic Else dielectric; interpolate = current#=b3dGetEntityMetallicFX(entity%): target#=1.0: new#=current#+(target#-current#)*speed#: b3dSetEntityMetallicFX(entity%, new#).

Typical values: wood/plastic/stone=0.0 (dielectric), painted surfaces=0.0 (paint is dielectric), bare metal=1.0 (iron/steel/aluminum), gold/silver/copper=1.0 (precious metals), avoid 0.3-0.7 range (unphysical, except for oxidized metals or dirt-covered surfaces).

Return values: -1.0 on error (invalid entity handle, non-mesh entity, prints error to stderr), 0.5 if mesh has no material (default PBR value), 0.0-1.0 actual metallic value (from material.metallicFactor field).

Performance: very fast O(1) lookup (simple material field access, ~0.0001ms), no calculation or GPU access required, suitable for per-frame queries.

Material override awareness: reads from correct material layer (override if exists, else base material), consistent with b3dSetEntityMetallicFX behavior (set and get use same material source).

PBR workflow: metallic/roughness workflow (used by BambooBasic), stores metallic in material.metallicFactor (0.0-1.0), optionally combined with metallicRoughnessTexture (texture.b=metallic, texture.g=roughness).

Related: b3dSetEntityMetallicFX sets metallic value, b3dGetEntityRoughnessFX reads roughness property, b3dSetEntityRoughnessFX sets roughness, b3dGetEntityAlphaFX/ColorFX read baseColor properties.