r3f-materials

React Three Fiber のマテリアル

まず、インストールされているレンダラー、Three.js、Fiber、Drei のバージョンを確認してください。サンプルは WebGL を使う Fiber 9／React 19 向けです。Drei のシェーダーベースのマテリアルが WebGPU でもそのまま動作するとは限りません。

要件に合う最もシンプルなマテリアルを選ぶ

要件	出発点	制約
非ライティングのアートや UI サーフェス	meshBasicMaterial	出力カラー／トーンマッピングの設定には引き続き影響されます
一般的な PBR サーフェス	meshStandardMaterial	金属では特に、環境光または適切なライトが必要です
クリアコート、透過、シーン	meshPhysicalMaterial	必要な機能だけを有効にしてください。シェーダー処理が増えます
スタイライズドライティング	meshToonMaterial	ライトが必要です。グラデーションマップには適切なフィルタリングが必要です
法線のデバッグ	meshNormalMaterial	ジオメトリ／法線の確認に役立ちます
カスタムシェーディング	ShaderMaterial またはノードマテリアル	WebGL／GLSL と WebGPU／TSL のどちらを使うかに合わせてください

環境ライティングを使った PBR サーフェス

Canvas の下にマウントします。この小規模なプロシージャル環境により、外部プリセットへの依存を避けられます。

import { Environment, Lightformer } from '@react-three/drei'

export default function Example() {
  return (
    <>
      <Environment resolution={64} frames={1}>
        <Lightformer position={[0, 3, 2]} scale={[5, 5, 1]} intensity={3} />
      </Environment>
      <mesh>
        <sphereGeometry args={[1, 32, 24]} />
        <meshStandardMaterial color="goldenrod" metalness={1} roughness={0.3} />
      </mesh>
    </>
  )
}

PBR とカラーに関する判断

• 誘電体ではメタルネスを 0 に近づけ、地金では 1 に近づけます。中間の値は通常、混合素材またはテクスチャのフィルタリングを表します。ラフネスはマイクロサーフェスの反応を制御するもので、不透明度ではありません。
• カラー／アルベドテクスチャとエミッシブテクスチャには sRGB を使い、ラフネス、メタルネス、法線、AO、マスクには NoColorSpace を使います。正しく読み込まれた glTF テクスチャのメタデータは保持してください。
• マップはスカラー設定に乗算されます。metalness={0} の場合、メタルネスマップは効果がありません。エミッシブマップには、黒以外のエミッシブカラーが必要です。
• 法線マップはシェーディングを変化させます。ディスプレイスメントマップは頂点を変化させるため、ジオメトリの細分化が十分に必要です。法線マップはシルエットを変化させません。
• エミッシブサーフェスは近くのジオメトリを照らさず、自動的にハローを生成することもありません。そのような効果が必要な場合は、適切なライティングとブルームのパイプラインを追加してください。
• PBR の見た目は、最近の Three.js のリリース間で変化しています。制御されたライティング／露出のもとで検証し、アップグレード時にライトを追加したりカラー変換を加えたりして、むやみに補正しないでください。

透明とガラス

• 通常のアルファブレンドには、opacity < 1 と transparent の両方が必要です。葉やデカールの切り抜きには、ソートによるアーティファクトを避けるため alphaTest を検討し、ソフトな透明度は必要な場合にのみ選んでください。
• depthWrite={false} は一部の透明レイヤーで役立ちますが、あらゆる場合に有効な解決策ではありません。重なり順、裏面、不透明オブジェクトとの交差をテストしてください。
• ガラスには物理ベースの透過を使い、通常は opacity を 1 にして、意味のある thickness／IOR を指定します。透過は通常の透明度と同じではありません。
• Drei の MeshTransmissionMaterial と MeshReflectorMaterial は、シーンのレンダーを追加します。まず低い解像度／サンプル数から始め、裏面パスやオブジェクトごとに独立したバッファーを有効にする前に計測してください。
• 透過サンプラーを共有すると、一部のシーンでは処理コストを抑えられますが、透明／透過オブジェクト間のあらゆる可視性を再現できるわけではありません。使用する前にヘルパーのドキュメントを読んでください。
• どこでも DoubleSide を有効にしないでください。レンダリングコストが変わるうえ、誤った巻き順や法線が見えなくなる可能性があります。

ライフタイムと更新

• オブジェクト間で外観を共有する場合は、マテリアルを共有してください。あるインスタンスのカラー、マップ、ユニフォームを変更する前にクローンしてください。キャッシュされた glTF マテリアルが別の場所でも使われている場合があります。
• R3F は宣言的なマテリアルの子を管理します。外部で割り当てたマテリアルや共有マテリアルのライフサイクルは、明示的に管理する必要があります。マテリアルを破棄しても、そのテクスチャは破棄されません。
• 型付き ref を使って通常のマテリアルプロパティをアニメーションさせます。ラフネスやカラーなどの値の変更には needsUpdate は不要ですが、マップの追加や削除などシェーダー機能の変更では再コンパイルが必要になる場合があります。
• マテリアル配列には、それに対応するジオメトリグループが必要です。配列だけでは、任意のマテリアルを面に割り当てられません。

検証

意図したライティングと出力パイプラインでレンダリングし、透明オブジェクトの重なり、シャドウ、マウントとアンマウントの繰り返しをテストしてください。透過や反射のパスを追加する前に、GPU コストを比較してください。

Sources

• MeshStandardMaterial, MeshPhysicalMaterial, Material.
• Drei transmission material, reflector material.
• Color management, Three.js migration guide.