threejs-syntax-materials

threejs-syntax-materials

クイックリファレンス

マテリアルタイプの選択ツリー

用途	マテリアル	理由
UI 要素、ライティングなしのシーン	MeshBasicMaterial	最も低負荷で、光の計算が不要です
マットな拡散反射（ローエンドデバイス向け）	MeshLambertMaterial	高速な拡散反射で、鏡面反射はありません
レガシーな鏡面ハイライト	MeshPhongMaterial	Blinn-Phong モデルで、物理的に正確ではありません
汎用 3D（推奨）	MeshStandardMaterial	PBR のメタリックネス／粗さで、業界標準です
ガラス、車の塗装、布、シャボン玉	MeshPhysicalMaterial	高度な PBR（クリアコート、透過、シーン、虹彩効果）
カートゥーン／アニメ調	MeshToonMaterial	段階的なセルシェーディング
スカルプトのプレビュー、ライトなし	MeshMatcapMaterial	Matcap テクスチャを使用し、ライトの設定は不要です
法線のデバッグ	MeshNormalMaterial	RGB で表面法線の方向を表します
透明なシャドウレシーバー	ShadowMaterial	透明なシャドウキャッチャーです
実線	LineBasicMaterial	シンプルな色付きの線です
破線	LineDashedMaterial	line.computeLineDistances() が必要です
パーティクル	PointsMaterial	点群のレンダリングです
ビルボード	SpriteMaterial	常にカメラの方向を向く四角形です

基本マテリアルプロパティ（全マテリアル共通）

プロパティ	型	デフォルト	説明
side	number	FrontSide	FrontSide、BackSide、または DoubleSide
transparent	boolean	false	アルファブレンディングを有効にします
opacity	number	1	1 未満の値を有効にするには、transparent: true が必要です
depthWrite	boolean	true	深度バッファに書き込みます
depthTest	boolean	true	深度バッファに対してテストします
blending	number	NormalBlending	NoBlending、AdditiveBlending、SubtractiveBlending、MultiplyBlending、CustomBlending
alphaTest	number	0	アルファ値がこの値を下回るフラグメントを破棄します
visible	boolean	true	このマテリアルをレンダリングするかどうか
wireframe	boolean	false	ワイヤーフレームのレンダリングモード
fog	boolean	true	シーンのフォグの影響を受けます
clippingPlanes	Plane[]	null	クリッピングプレーンの配列
clipIntersection	boolean	false	すべてのプレーンが交差する部分でクリップします（和集合ではありません）
needsUpdate	boolean	false	シェーダーを再コンパイルするには true に設定します
toneMapped	boolean	true	レンダラーのトーンマッピングを適用します

基本マテリアルメソッド

メソッド	シグネチャ	説明
clone	(): Material	マテリアルを複製します
copy	(source: Material): Material	source からプロパティをコピーします
dispose	(): void	GPU リソースを解放します。削除するときは必ず呼び出してください
onBeforeCompile	(shader, renderer): void	コンパイル前にシェーダーを変更するためのフックです
setValues	(values: Object): void	複数のプロパティを一度に設定します

重要な警告

transparent: true を指定せずに opacity < 1 を設定しては絶対にいけません。opacity の値は無視されます。必ず両方をセットで指定してください。

MeshStandardMaterial で十分な場合に MeshPhysicalMaterial を使っては絶対にいけません。Physical は大幅に大きなシェーダーをコンパイルします。クリアコート、透過、シーン、イリデッセンス、または異方性が必要な場合にのみ使用してください。

法線マップ、粗さマップ、メタルネスマップ、またはデータテクスチャに SRGBColorSpace を設定しては絶対にいけません。データが破損し、ライティングが不正になります。SRGBColorSpace はディフューズ／カラー／エミッシブテクスチャにのみ設定してください。

オブジェクトを削除する際に material.dispose() と texture.dispose() の呼び出しを忘れては絶対にいけません。GPU メモリリークが蓄積し、アプリケーションがクラッシュします。

LineBasicMaterial で linewidth > 1 を設定しては絶対にいけません。WebGL の制限により、ほとんどのプラットフォームでは無視されます。太い線には必ず three/addons/lines/ の Line2 と LineMaterial を使用してください。

シェーダーのコンパイルに影響するプロパティを変更した後は、必ず material.needsUpdate = true を設定してください（例：flatShading の切り替え、side の変更、実行時のテクスチャマップの追加／削除）。

texture.repeat に (1, 1) 以外の値を使用する場合は、必ず wrapS と wrapT を RepeatWrapping に設定してください。デフォルトの ClampToEdgeWrapping ではテクスチャはタイル状に繰り返されません。

---

MeshStandardMaterial（PBR）

ほとんどの 3D シーンに推奨されるマテリアルです。物理ベースのメタルネス／粗さワークフローを使用します。

import { MeshStandardMaterial, TextureLoader, SRGBColorSpace, RepeatWrapping } from 'three';

const loader = new TextureLoader();
const material = new MeshStandardMaterial({
  color: 0xffffff,
  roughness: 0.7,           // 0 = mirror, 1 = fully rough
  metalness: 0.0,           // 0 = dielectric, 1 = metal
  map: null,                // Diffuse/albedo texture
  roughnessMap: null,       // Per-pixel roughness
  metalnessMap: null,       // Per-pixel metalness
  normalMap: null,          // Surface normal perturbation
  normalScale: new Vector2(1, 1),
  aoMap: null,              // Ambient occlusion (requires uv2)
  aoMapIntensity: 1.0,
  emissive: 0x000000,       // Emissive color
  emissiveMap: null,        // Emissive texture
  emissiveIntensity: 1.0,
  envMap: null,             // Environment reflection map
  envMapIntensity: 1.0,
  bumpMap: null,            // Grayscale height map
  bumpScale: 1.0,
  displacementMap: null,    // Vertex displacement map
  displacementScale: 1.0,
  displacementBias: 0.0,
  alphaMap: null,           // Per-pixel transparency
  lightMap: null,           // Baked lighting (requires uv2)
  lightMapIntensity: 1.0,
  flatShading: false,
  wireframe: false,
  fog: true
});

---

MeshPhysicalMaterial（高度な PBR）

MeshStandardMaterial のすべてのプロパティに加え、以下を拡張します。

プロパティ	型	デフォルト	説明
clearcoat	float	0.0	クリアコート層の強度（0～1）
clearcoatRoughness	float	0.0	クリアコートの粗さ
clearcoatMap	Texture	null	クリアコート強度マップ
clearcoatNormalMap	Texture	null	クリアコート法線マップ
transmission	float	0.0	物理ベースの透過（0～1）
transmissionMap	Texture	null	透過マップ
thickness	float	0.0	透過におけるボリュームの厚さ
thicknessMap	Texture	null	厚さマップ
ior	float	1.5	屈折率（1.0～2.333）
attenuationDistance	float	Infinity	ボリューム内での光の減衰距離
attenuationColor	Color	white	光の減衰色
sheen	float	0.0	シーン層の強度（布のような質感）
sheenColor	Color	0x000000	シーンの色合い
sheenRoughness	float	1.0	シーンの粗さ
iridescence	float	0.0	薄膜干渉（0～1）
iridescenceIOR	float	1.3	イリデッセンスの屈折率
iridescenceThicknessRange	[float, float]	[100, 400]	薄膜の厚さの範囲（nm）
anisotropy	float	0.0	異方性反射の強度
anisotropyRotation	float	0.0	異方性の回転（ラジアン）
specularIntensity	float	1.0	鏡面反射層の強度
specularColor	Color	white	鏡面反射の色合い
dispersion	float	0.0	色分散（虹色効果）
reflectivity	float	0.5	法線入射時の反射率

---

テクスチャシステム

カラースペースのルール（重要）

マップの種類	カラースペース	使用チャンネル
map（ディフューズ／アルベド）	SRGBColorSpace	RGB(A)
emissiveMap	SRGBColorSpace	RGB
lightMap	SRGBColorSpace	RGB
envMap	SRGBColorSpace	RGB
sheenColorMap	SRGBColorSpace	RGB
specularColorMap	SRGBColorSpace	RGB
normalMap	NoColorSpace	RGB
roughnessMap	NoColorSpace	G チャンネル
metalnessMap	NoColorSpace	B チャンネル
aoMap	NoColorSpace	R チャンネル
bumpMap	NoColorSpace	R チャンネル
displacementMap	NoColorSpace	R チャンネル
alphaMap	NoColorSpace	R チャンネル
clearcoatMap	NoColorSpace	R チャンネル
clearcoatRoughnessMap	NoColorSpace	R チャンネル
clearcoatNormalMap	NoColorSpace	RGB
transmissionMap	NoColorSpace	R チャンネル
thicknessMap	NoColorSpace	R チャンネル
iridescenceMap	NoColorSpace	R チャンネル
iridescenceThicknessMap	NoColorSpace	R チャンネル
sheenRoughnessMap	NoColorSpace	R チャンネル
anisotropyMap	NoColorSpace	RG チャンネル
specularIntensityMap	NoColorSpace	A チャンネル

ルール：ディフューズ／エミッシブ／カラーのテクスチャには SRGBColorSpace を使用します。すべてのデータテクスチャには NoColorSpace を使用します。設定を誤ると、レンダリングが白っぽくなったり、彩度が過剰になったりします。

テクスチャローダー

ローダー	形式	インポート
TextureLoader	PNG、JPG、WebP	three コア
CubeTextureLoader	6 面の PNG/JPG キューブマップ	three コア
RGBELoader	.hdr（Radiance HDR）	three/addons/loaders/RGBELoader.js
EXRLoader	.exr（OpenEXR HDR）	three/addons/loaders/EXRLoader.js
KTX2Loader	.ktx2（GPU 圧縮）	three/addons/loaders/KTX2Loader.js

ラップモード

定数	説明
ClampToEdgeWrapping	端のテクセルを引き伸ばします（デフォルト）
RepeatWrapping	テクスチャをタイル状に繰り返します
MirroredRepeatWrapping	ミラー反転を交互に行いながらタイル状に繰り返します

フィルターモード

定数	種類	説明
NearestFilter	拡大／縮小	ピクセル感のある鮮明な表示（レトロ調、トゥーン調のグラデーション）
LinearFilter	拡大／縮小	滑らかな補間
LinearMipmapLinearFilter	縮小	トライリニアフィルタリング（デフォルト、最高品質）

テクスチャのプロパティ

プロパティ	型	デフォルト	説明
wrapS / wrapT	number	ClampToEdgeWrapping	ラップモード
magFilter	number	LinearFilter	拡大フィルター
minFilter	number	LinearMipmapLinearFilter	縮小フィルター
anisotropy	number	1	異方性フィルタリング（最大値 = renderer.capabilities.getMaxAnisotropy()）
repeat	Vector2	(1, 1)	UV の繰り返し回数
offset	Vector2	(0, 0)	UV オフセット
rotation	number	0	UV の回転角度（ラジアン）
center	Vector2	(0, 0)	回転の中心
flipY	boolean	true	アップロード時に垂直方向に反転
colorSpace	string	NoColorSpace	カラースペースの解釈
generateMipmaps	boolean	true	ミップマップを自動生成
needsUpdate	boolean	false	GPU への再アップロードを実行

flipY のルール

• flipY = true（デフォルト）：読み込んだ画像テクスチャ（PNG、JPG）に適しています
• flipY = false：WebGLRenderTarget のテクスチャ、DataTexture、フレームバッファーテクスチャには必ず使用します

---

マテリアルの破棄

// ALWAYS dispose materials and textures when removing objects
function disposeMesh(mesh) {
  if (mesh.material) {
    // Dispose all texture maps
    for (const key of Object.keys(mesh.material)) {
      const value = mesh.material[key];
      if (value && value.isTexture) {
        value.dispose();
      }
    }
    mesh.material.dispose();
  }
  if (mesh.geometry) {
    mesh.geometry.dispose();
  }
}

---

needsUpdate フラグ

実行時に以下を変更した後は、必ず material.needsUpdate = true を設定してください：

• flatShading の切り替え
• side の変更（FrontSide/BackSide/DoubleSide）
• テクスチャマップの追加または削除（例：map を null からテクスチャに変更）
• transparent または alphaTest の変更
• wireframe の切り替え
• コンパイルされるシェーダーバリアントを変更するプロパティ

毎フレーム needsUpdate = true を設定してはいけません。シェーダーの再コンパイルに大きなコストがかかります。プロパティを変更した後に一度だけ設定してください。

テクスチャの場合：texture.image のデータを変更した後、GPU への再アップロードを実行するために texture.needsUpdate = true を設定してください。

---

トゥーンマテリアルの特別ルール

MeshToonMaterial を使用する場合は、必ず gradientMap.minFilter = NearestFilter と gradientMap.magFilter = NearestFilter を設定してください。線形フィルタリングでは、段階的な陰影がぼやけて滑らかなグラデーションになり、トゥーン効果が損なわれます。

---

参考リンク

• references/methods.md -- コンストラクターのシグネチャと主要なプロパティを含む、すべてのマテリアルタイプ
• references/examples.md -- 動作する完全なサンプル（PBR、テクスチャ、複数マテリアル）
• references/anti-patterns.md -- 避けるべきことと、その説明

公式ソース

• https://threejs.org/docs/#api/en/materials/Material
• https://threejs.org/docs/#api/en/materials/MeshStandardMaterial
• https://threejs.org/docs/#api/en/materials/MeshPhysicalMaterial
• https://threejs.org/docs/#api/en/textures/Texture