r3f-materials

What this skill does

# React Three Fiber Materials

## Quick Start

```tsx
import { Canvas } from '@react-three/fiber'

function Scene() {
  return (
    <Canvas>
      <ambientLight intensity={0.5} />
      <directionalLight position={[5, 5, 5]} />

      <mesh>
        <boxGeometry />
        <meshStandardMaterial
          color="hotpink"
          roughness={0.5}
          metalness={0.5}
        />
      </mesh>
    </Canvas>
  )
}
```

## Material Types Overview

| Material | Use Case | Lighting |
|----------|----------|----------|
| meshBasicMaterial | Unlit, flat colors | No |
| meshLambertMaterial | Matte surfaces, fast | Yes (diffuse) |
| meshPhongMaterial | Shiny, specular | Yes |
| meshStandardMaterial | PBR, realistic | Yes (PBR) |
| meshPhysicalMaterial | Advanced PBR | Yes (PBR+) |
| meshToonMaterial | Cel-shaded | Yes (toon) |
| meshNormalMaterial | Debug normals | No |
| shaderMaterial | Custom GLSL | Custom |

## meshBasicMaterial

No lighting calculations. Always visible, fast.

```tsx
<mesh>
  <boxGeometry />
  <meshBasicMaterial
    color="red"
    transparent
    opacity={0.5}
    side={THREE.DoubleSide}  // FrontSide, BackSide, DoubleSide
    wireframe={false}
    map={colorTexture}
    alphaMap={alphaTexture}
    envMap={envTexture}
    fog={true}
  />
</mesh>
```

## meshStandardMaterial (PBR)

Physically-based rendering. Recommended for realistic results.

```tsx
import { useTexture } from '@react-three/drei'
import * as THREE from 'three'

function PBRMesh() {
  // Load PBR texture set
  const [colorMap, normalMap, roughnessMap, metalnessMap, aoMap] = useTexture([
    '/textures/color.jpg',
    '/textures/normal.jpg',
    '/textures/roughness.jpg',
    '/textures/metalness.jpg',
    '/textures/ao.jpg',
  ])

  return (
    <mesh>
      <sphereGeometry args={[1, 64, 64]} />
      <meshStandardMaterial
        // Base color
        color="#ffffff"
        map={colorMap}

        // PBR properties
        roughness={1}         // 0 = mirror, 1 = diffuse
        roughnessMap={roughnessMap}
        metalness={0}         // 0 = dielectric, 1 = metal
        metalnessMap={metalnessMap}

        // Surface detail
        normalMap={normalMap}
        normalScale={[1, 1]}

        // Ambient occlusion (requires uv2)
        aoMap={aoMap}
        aoMapIntensity={1}

        // Emissive
        emissive="#000000"
        emissiveIntensity={1}
        emissiveMap={emissiveTexture}

        // Environment
        envMap={envTexture}
        envMapIntensity={1}

        // Other
        flatShading={false}
        fog={true}
        transparent={false}
      />
    </mesh>
  )
}
```

## meshPhysicalMaterial (Advanced PBR)

Extends Standard with clearcoat, transmission, sheen, etc.

```tsx
// Glass material
function Glass() {
  return (
    <mesh>
      <sphereGeometry args={[1, 64, 64]} />
      <meshPhysicalMaterial
        color="#ffffff"
        metalness={0}
        roughness={0}
        transmission={1}      // 0 = opaque, 1 = fully transparent
        thickness={0.5}       // Volume thickness for refraction
        ior={1.5}             // Index of refraction (glass ~1.5)
        envMapIntensity={1}
      />
    </mesh>
  )
}

// Car paint
function CarPaint() {
  return (
    <mesh>
      <boxGeometry />
      <meshPhysicalMaterial
        color="#ff0000"
        metalness={0.9}
        roughness={0.5}
        clearcoat={1}              // Clearcoat layer strength
        clearcoatRoughness={0.1}   // Clearcoat roughness
      />
    </mesh>
  )
}

// Fabric/velvet (sheen)
function Fabric() {
  return (
    <mesh>
      <sphereGeometry args={[1, 64, 64]} />
      <meshPhysicalMaterial
        color="#8844aa"
        roughness={0.8}
        sheen={1}
        sheenRoughness={0.5}
        sheenColor="#ff88ff"
      />
    </mesh>
  )
}

// Iridescent (soap bubbles)
function Iridescent() {
  return (
    <mesh>
      <sphereGeometry args={[1, 64, 64]} />
      <meshPhysicalMaterial
        color="#ffffff"
        iridescence={1}
        iridescenceIOR={1.3}
        iridescenceThicknessRange={[100, 400]}
      />
    </mesh>
  )
}
```

## Drei Special Materials

### MeshReflectorMaterial

Realistic mirror-like reflections.

```tsx
import { MeshReflectorMaterial } from '@react-three/drei'

function ReflectiveFloor() {
  return (
    <mesh rotation={[-Math.PI / 2, 0, 0]} position={[0, -0.5, 0]}>
      <planeGeometry args={[10, 10]} />
      <MeshReflectorMaterial
        blur={[400, 100]}         // Blur amount [x, y]
        resolution={1024}         // Reflection resolution
        mixBlur={1}               // Mix blur with reflection
        mixStrength={0.5}         // Reflection strength
        roughness={1}
        depthScale={1.2}
        minDepthThreshold={0.4}
        maxDepthThreshold={1.4}
        color="#333"
        metalness={0.5}
        mirror={0.5}
      />
    </mesh>
  )
}
```

### MeshWobbleMaterial

Animated wobble effect.

```tsx
import { MeshWobbleMaterial } from '@react-three/drei'

function WobblyMesh() {
  return (
    <mesh>
      <torusKnotGeometry args={[1, 0.4, 100, 16]} />
      <MeshWobbleMaterial
        factor={1}       // Wobble amplitude
        speed={2}        // Wobble speed
        color="hotpink"
        metalness={0}
        roughness={0.5}
      />
    </mesh>
  )
}
```

### MeshDistortMaterial

Perlin noise distortion.

```tsx
import { MeshDistortMaterial } from '@react-three/drei'

function DistortedMesh() {
  return (
    <mesh>
      <sphereGeometry args={[1, 64, 64]} />
      <MeshDistortMaterial
        distort={0.5}    // Distortion amount
        speed={2}        // Animation speed
        color="cyan"
        roughness={0.2}
      />
    </mesh>
  )
}
```

### MeshTransmissionMaterial

Better glass/refractive materials.

```tsx
import { MeshTransmissionMaterial } from '@react-three/drei'

function GlassSphere() {
  return (
    <mesh>
      <sphereGeometry args={[1, 64, 64]} />
      <MeshTransmissionMaterial
        backside              // Render backside
        samples={16}          // Refraction samples
        resolution={1024}     // Buffer resolution
        transmission={1}      // Transmission factor
        roughness={0.0}
        thickness={0.5}       // Volume thickness
        ior={1.5}             // Index of refraction
        chromaticAberration={0.06}
        anisotropy={0.1}
        distortion={0.0}
        distortionScale={0.3}
        temporalDistortion={0.5}
        clearcoat={1}
        attenuationDistance={0.5}
        attenuationColor="#ffffff"
        color="#c9ffa1"
      />
    </mesh>
  )
}
```

### MeshDiscardMaterial

Discard fragments - useful for shadows only.

```tsx
import { MeshDiscardMaterial } from '@react-three/drei'

function ShadowOnlyMesh() {
  return (
    <mesh castShadow>
      <boxGeometry />
      <MeshDiscardMaterial />  {/* Invisible but casts shadows */}
    </mesh>
  )
}
```

## Points and Lines Materials

```tsx
// Points material
<points>
  <bufferGeometry />
  <pointsMaterial
    size={0.1}
    sizeAttenuation={true}
    color="white"
    map={spriteTexture}
    transparent
    alphaTest={0.5}
    vertexColors
  />
</points>

// Line materials
<line>
  <bufferGeometry />
  <lineBasicMaterial color="white" linewidth={1} />
</line>

<line>
  <bufferGeometry />
  <lineDashedMaterial
    color="white"
    dashSize={0.5}
    gapSize={0.25}
    scale={1}
  />
</line>
```

## Common Material Properties

All materials share these base properties:

```tsx
<meshStandardMaterial
  // Visibility
  visible={true}
  transparent={false}
  opacity={1}
  alphaTest={0}          // Discard pixels with alpha < value

  // Rendering
  side={THREE.FrontSide} // FrontSide, BackSide, DoubleSide
  depthTest={true}
  depthWrite={true}
  colorWrite={true}

  // Blending
  blending={THREE.NormalBlending}
  // NormalBlending, AdditiveBlending, SubtractiveBlending, MultiplyBlending

  // Polygon offset (z-fighting fix)
  polygonOffset={false}
  polygonOffsetFactor={0}
  polygonOff