0
# Materials
1

2
Material system defining surface appearance, lighting response, and rendering properties for 3D objects. Materials control how light interacts with surfaces through physically-based and artistic shading models.
3

4
## Capabilities
5

6
### Material Base Class
7

8
Abstract foundation providing common material properties for blending, transparency, culling, and rendering state.
9

10
```typescript { .api }
11
import { 
12
  Material,
13
  EventDispatcher,
14
  Color,
15
  Texture,
16
  Plane,
17
  Side,
18
  Blending,
19
  BlendingEquation,
20
  BlendingFactor,
21
  DepthMode,
22
  StencilFunc,
23
  StencilOp
24
} from 'three';
25

26
/**
27
 * Abstract base class for all materials defining surface appearance
28
 */
29
abstract class Material extends EventDispatcher {
30
  /** Type flag for material detection */
31
  readonly isMaterial: true;
32
  
33
  /** Unique material ID */
34
  readonly id: number;
35
  
36
  /** UUID string identifier */
37
  readonly uuid: string;
38
  
39
  /** Material name */
40
  name: string;
41
  
42
  /** Material type string */
43
  readonly type: string;
44
  
45
  /** Fog affect material */
46
  fog: boolean;
47
  
48
  /** Blending mode */
49
  blending: Blending;
50
  
51
  /** Face culling side */
52
  side: Side;
53
  
54
  /** Use vertex colors */
55
  vertexColors: boolean;
56
  
57
  /** Material opacity (0-1) */
58
  opacity: number;
59
  
60
  /** Enable transparency */
61
  transparent: boolean;
62
  
63
  /** Alpha hashed transparency */
64
  alphaHash: boolean;
65
  
66
  /** Alpha test threshold */
67
  alphaTest: number;
68
  
69
  /** Alpha test texture */
70
  alphaMap: Texture | null;
71
  
72
  /** Blending source factor */
73
  blendSrc: BlendingFactor;
74
  
75
  /** Blending destination factor */
76
  blendDst: BlendingFactor;
77
  
78
  /** Blending equation */
79
  blendEquation: BlendingEquation;
80
  
81
  /** Alpha channel blending source */
82
  blendSrcAlpha: BlendingFactor | null;
83
  
84
  /** Alpha channel blending destination */
85
  blendDstAlpha: BlendingFactor | null;
86
  
87
  /** Alpha channel blending equation */
88
  blendEquationAlpha: BlendingEquation | null;
89
  
90
  /** Constant blend color */
91
  blendColor: Color;
92
  
93
  /** Constant blend alpha */
94
  blendAlpha: number;
95
  
96
  /** Enable depth testing */
97
  depthTest: boolean;
98
  
99
  /** Enable depth writing */
100
  depthWrite: boolean;
101
  
102
  /** Depth comparison function */
103
  depthFunc: DepthMode;
104
  
105
  /** Enable stencil testing */
106
  stencilWrite: boolean;
107
  
108
  /** Stencil test function */
109
  stencilFunc: StencilFunc;
110
  
111
  /** Stencil reference value */
112
  stencilRef: number;
113
  
114
  /** Stencil function mask */
115
  stencilFuncMask: number;
116
  
117
  /** Stencil fail operation */
118
  stencilFail: StencilOp;
119
  
120
  /** Stencil Z-fail operation */
121
  stencilZFail: StencilOp;
122
  
123
  /** Stencil Z-pass operation */
124
  stencilZPass: StencilOp;
125
  
126
  /** Stencil write mask */
127
  stencilWriteMask: number;
128
  
129
  /** Clipping planes */
130
  clippingPlanes: Plane[] | null;
131
  
132
  /** Clip intersection mode */
133
  clipIntersection: boolean;
134
  
135
  /** Clip shadows */
136
  clipShadows: boolean;
137
  
138
  /** Color write mask */
139
  colorWrite: boolean;
140
  
141
  /** Polygon offset */
142
  polygonOffset: boolean;
143
  
144
  /** Polygon offset factor */
145
  polygonOffsetFactor: number;
146
  
147
  /** Polygon offset units */
148
  polygonOffsetUnits: number;
149
  
150
  /** Dithering */
151
  dithering: boolean;
152
  
153
  /** Premultiplied alpha */
154
  premultipliedAlpha: boolean;
155
  
156
  /** Force single pass rendering */
157
  forceSinglePass: boolean;
158
  
159
  /** Material visible */
160
  visible: boolean;
161
  
162
  /** Tone mapping */
163
  toneMapped: boolean;
164
  
165
  /** User data */
166
  userData: Record<string, any>;
167
  
168
  /** Material version for cache invalidation */
169
  readonly version: number;
170
  
171
  /**
172
   * Create material base
173
   */
174
  constructor();
175
  
176
  /**
177
   * Called when material needs compilation
178
   * @param parameters - Shader compilation parameters
179
   */
180
  onBuild(shaderData: any, renderer: any): void;
181
  
182
  /**
183
   * Called before rendering for custom uniforms
184
   * @param shader - Shader program
185
   * @param renderer - WebGL renderer
186
   * @param scene - Scene being rendered
187
   * @param camera - Active camera
188
   * @param geometry - Object geometry
189
   * @param object - Object being rendered
190
   */
191
  onBeforeRender(
192
    renderer: any,
193
    scene: any,
194
    camera: any,
195
    geometry: any,
196
    object: any,
197
    group: any
198
  ): void;
199
  
200
  /**
201
   * Called before compiling shader
202
   * @param shader - Shader object
203
   * @param renderer - WebGL renderer
204
   */
205
  onBeforeCompile(shader: any, renderer: any): void;
206
  
207
  /**
208
   * Get custom shader modification
209
   * @param shader - Base shader
210
   * @returns Modified shader or null
211
   */
212
  customProgramCacheKey(): string;
213
  
214
  /**
215
   * Set material properties from object
216
   * @param values - Property values
217
   * @returns This material for chaining
218
   */
219
  setValues(values: Record<string, any>): this;
220
  
221
  /**
222
   * Serialize to JSON
223
   * @param meta - Metadata object
224
   * @returns JSON representation
225
   */
226
  toJSON(meta?: any): any;
227
  
228
  /**
229
   * Clone material
230
   * @returns Cloned material
231
   */
232
  clone(): this;
233
  
234
  /**
235
   * Copy properties from another material
236
   * @param source - Source material
237
   * @returns This material for chaining
238
   */
239
  copy(source: Material): this;
240
  
241
  /**
242
   * Dispose material resources
243
   */
244
  dispose(): void;
245
}
246
```
247

248
**Usage Examples:**
249

250
```typescript
251
import { Material, Color, AdditiveBlending, DoubleSide } from 'three';
252

253
// Material configuration
254
material.transparent = true;
255
material.opacity = 0.7;
256
material.side = DoubleSide;
257
material.blending = AdditiveBlending;
258

259
// Depth and stencil
260
material.depthTest = false;
261
material.depthWrite = false;
262

263
// Custom uniforms
264
material.onBeforeRender = function(renderer, scene, camera, geometry, object) {
265
  this.uniforms.time.value = performance.now() / 1000;
266
};
267

268
// Material versioning
269
material.needsUpdate = true; // Forces recompilation
270
```
271

272
### Physically Based Materials
273

274
Modern PBR materials using metallic-roughness workflow for realistic lighting and surface response.
275

276
```typescript { .api }
277
import { 
278
  MeshStandardMaterial,
279
  MeshPhysicalMaterial,
280
  Material,
281
  Color,
282
  Texture,
283
  Vector2,
284
  NormalMapType
285
} from 'three';
286

287
/**
288
 * Physically-based standard material using metallic-roughness workflow
289
 */
290
class MeshStandardMaterial extends Material {
291
  /** Type flag for standard material detection */
292
  readonly isMeshStandardMaterial: true;
293
  
294
  /** Shader defines */
295
  defines: Record<string, any>;
296
  
297
  /** Base color (albedo) */
298
  color: Color;
299
  
300
  /** Surface roughness (0 = mirror, 1 = fully rough) */
301
  roughness: number;
302
  
303
  /** Metallic property (0 = dielectric, 1 = metallic) */
304
  metalness: number;
305
  
306
  /** Albedo/diffuse texture */
307
  map: Texture | null;
308
  
309
  /** Lightmap texture */
310
  lightMap: Texture | null;
311
  
312
  /** Lightmap intensity */
313
  lightMapIntensity: number;
314
  
315
  /** Ambient occlusion map */
316
  aoMap: Texture | null;
317
  
318
  /** AO map intensity */
319
  aoMapIntensity: number;
320
  
321
  /** Emissive color */
322
  emissive: Color;
323
  
324
  /** Emissive intensity */
325
  emissiveIntensity: number;
326
  
327
  /** Emissive texture */
328
  emissiveMap: Texture | null;
329
  
330
  /** Bump map for surface detail */
331
  bumpMap: Texture | null;
332
  
333
  /** Bump map scale */
334
  bumpScale: number;
335
  
336
  /** Normal map for surface normals */
337
  normalMap: Texture | null;
338
  
339
  /** Normal map type */
340
  normalMapType: NormalMapType;
341
  
342
  /** Normal map scale */
343
  normalScale: Vector2;
344
  
345
  /** Displacement map */
346
  displacementMap: Texture | null;
347
  
348
  /** Displacement scale */
349
  displacementScale: number;
350
  
351
  /** Displacement bias */
352
  displacementBias: number;
353
  
354
  /** Roughness map */
355
  roughnessMap: Texture | null;
356
  
357
  /** Metalness map */
358
  metalnessMap: Texture | null;
359
  
360
  /** Environment map */
361
  envMap: Texture | null;
362
  
363
  /** Environment map intensity */
364
  envMapIntensity: number;
365
  
366
  /** Environment map rotation */
367
  envMapRotation: Euler;
368
  
369
  /** Wireframe mode */
370
  wireframe: boolean;
371
  
372
  /** Wireframe line width */
373
  wireframeLinewidth: number;
374
  
375
  /** Wireframe line cap */
376
  wireframeLinecap: string;
377
  
378
  /** Wireframe line join */
379
  wireframeLinejoin: string;
380
  
381
  /** Flat shading */
382
  flatShading: boolean;
383
  
384
  /**
385
   * Create standard material
386
   * @param parameters - Material parameters
387
   */
388
  constructor(parameters?: Partial<MeshStandardMaterial>);
389
  
390
  /**
391
   * Copy properties from another standard material
392
   * @param source - Source material
393
   * @returns This material for chaining
394
   */
395
  copy(source: MeshStandardMaterial): this;
396
}
397

398
/**
399
 * Extended physically-based material with additional effects
400
 */
401
class MeshPhysicalMaterial extends MeshStandardMaterial {
402
  /** Type flag for physical material detection */
403
  readonly isMeshPhysicalMaterial: true;
404
  
405
  /** Clearcoat layer intensity */
406
  clearcoat: number;
407
  
408
  /** Clearcoat roughness */
409
  clearcoatRoughness: number;
410
  
411
  /** Clearcoat texture */
412
  clearcoatMap: Texture | null;
413
  
414
  /** Clearcoat roughness map */
415
  clearcoatRoughnessMap: Texture | null;
416
  
417
  /** Clearcoat normal map */
418
  clearcoatNormalMap: Texture | null;
419
  
420
  /** Clearcoat normal scale */
421
  clearcoatNormalScale: Vector2;
422
  
423
  /** Index of refraction (IOR) */
424
  ior: number;
425
  
426
  /** Reflectivity for non-metals */
427
  reflectivity: number;
428
  
429
  /** Iridescence effect intensity */
430
  iridescence: number;
431
  
432
  /** Iridescence texture */
433
  iridescenceMap: Texture | null;
434
  
435
  /** Iridescence index of refraction */
436
  iridescenceIOR: number;
437
  
438
  /** Iridescence thickness range */
439
  iridescenceThicknessRange: [number, number];
440
  
441
  /** Iridescence thickness map */
442
  iridescenceThicknessMap: Texture | null;
443
  
444
  /** Sheen effect intensity */
445
  sheen: number;
446
  
447
  /** Sheen color */
448
  sheenColor: Color;
449
  
450
  /** Sheen color map */
451
  sheenColorMap: Texture | null;
452
  
453
  /** Sheen roughness */
454
  sheenRoughness: number;
455
  
456
  /** Sheen roughness map */
457
  sheenRoughnessMap: Texture | null;
458
  
459
  /** Transmission for glass-like materials */
460
  transmission: number;
461
  
462
  /** Transmission map */
463
  transmissionMap: Texture | null;
464
  
465
  /** Thickness for subsurface scattering */
466
  thickness: number;
467
  
468
  /** Thickness map */
469
  thicknessMap: Texture | null;
470
  
471
  /** Attenuation distance */
472
  attenuationDistance: number;
473
  
474
  /** Attenuation color */
475
  attenuationColor: Color;
476
  
477
  /** Specular intensity */
478
  specularIntensity: number;
479
  
480
  /** Specular intensity map */
481
  specularIntensityMap: Texture | null;
482
  
483
  /** Specular color */
484
  specularColor: Color;
485
  
486
  /** Specular color map */
487
  specularColorMap: Texture | null;
488
  
489
  /** Anisotropy for stretched highlights */
490
  anisotropy: number;
491
  
492
  /** Anisotropy rotation */
493
  anisotropyRotation: number;
494
  
495
  /** Anisotropy map */
496
  anisotropyMap: Texture | null;
497
  
498
  /**
499
   * Create physical material
500
   * @param parameters - Material parameters
501
   */
502
  constructor(parameters?: Partial<MeshPhysicalMaterial>);
503
}
504
```
505

506
**Usage Examples:**
507

508
```typescript
509
import { MeshStandardMaterial, MeshPhysicalMaterial, TextureLoader } from 'three';
510

511
// Standard PBR material
512
const standardMaterial = new MeshStandardMaterial({
513
  color: 0x808080,
514
  roughness: 0.4,
515
  metalness: 0.1
516
});
517

518
// Load textures
519
const loader = new TextureLoader();
520
const albedo = loader.load('textures/albedo.jpg');
521
const normal = loader.load('textures/normal.jpg');
522
const roughness = loader.load('textures/roughness.jpg');
523
const metalness = loader.load('textures/metalness.jpg');
524
const ao = loader.load('textures/ao.jpg');
525

526
// Textured material
527
const texturedMaterial = new MeshStandardMaterial({
528
  map: albedo,
529
  normalMap: normal,
530
  roughnessMap: roughness,
531
  metalnessMap: metalness,
532
  aoMap: ao,
533
  aoMapIntensity: 1.0
534
});
535

536
// Car paint material
537
const carPaint = new MeshPhysicalMaterial({
538
  color: 0x0066cc,
539
  roughness: 0.05,
540
  metalness: 0.9,
541
  clearcoat: 1.0,
542
  clearcoatRoughness: 0.03
543
});
544

545
// Glass material
546
const glass = new MeshPhysicalMaterial({
547
  color: 0xffffff,
548
  roughness: 0,
549
  metalness: 0,
550
  transmission: 1,
551
  transparent: true,
552
  ior: 1.5
553
});
554

555
// Fabric with sheen
556
const fabric = new MeshPhysicalMaterial({
557
  color: 0x440066,
558
  roughness: 0.8,
559
  metalness: 0,
560
  sheen: 1,
561
  sheenColor: new Color(0x663399),
562
  sheenRoughness: 0.5
563
});
564
```
565

566
### Basic Materials
567

568
Simple materials for unlit surfaces, debugging, and special effects without complex lighting calculations.
569

570
```typescript { .api }
571
import { 
572
  MeshBasicMaterial,
573
  MeshLambertMaterial,
574
  MeshPhongMaterial,
575
  MeshToonMaterial,
576
  MeshNormalMaterial,
577
  MeshMatcapMaterial,
578
  MeshDepthMaterial,
579
  MeshDistanceMaterial,
580
  LineBasicMaterial,
581
  LineDashedMaterial,
582
  PointsMaterial,
583
  SpriteMaterial,
584
  ShadowMaterial
585
} from 'three';
586

587
/**
588
 * Basic material without lighting calculations
589
 */
590
class MeshBasicMaterial extends Material {
591
  /** Type flag for basic material detection */
592
  readonly isMeshBasicMaterial: true;
593
  
594
  /** Base color */
595
  color: Color;
596
  
597
  /** Color texture */
598
  map: Texture | null;
599
  
600
  /** Lightmap texture */
601
  lightMap: Texture | null;
602
  
603
  /** Lightmap intensity */
604
  lightMapIntensity: number;
605
  
606
  /** Ambient occlusion map */
607
  aoMap: Texture | null;
608
  
609
  /** AO intensity */
610
  aoMapIntensity: number;
611
  
612
  /** Specular map for reflectivity */
613
  specularMap: Texture | null;
614
  
615
  /** Alpha map */
616
  alphaMap: Texture | null;
617
  
618
  /** Environment map */
619
  envMap: Texture | null;
620
  
621
  /** Environment map rotation */
622
  envMapRotation: Euler;
623
  
624
  /** Combine mode for environment map */
625
  combine: Combine;
626
  
627
  /** Reflectivity for environment map */
628
  reflectivity: number;
629
  
630
  /** Refraction ratio for environment map */
631
  refractionRatio: number;
632
  
633
  /** Wireframe mode */
634
  wireframe: boolean;
635
  
636
  /** Wireframe line width */
637
  wireframeLinewidth: number;
638
  
639
  /** Wireframe line cap */
640
  wireframeLinecap: string;
641
  
642
  /** Wireframe line join */
643
  wireframeLinejoin: string;
644
  
645
  /**
646
   * Create basic material
647
   * @param parameters - Material parameters
648
   */
649
  constructor(parameters?: Partial<MeshBasicMaterial>);
650
}
651

652
/**
653
 * Lambert diffuse material
654
 */
655
class MeshLambertMaterial extends Material {
656
  /** Type flag for Lambert material detection */
657
  readonly isMeshLambertMaterial: true;
658
  
659
  /** Diffuse color */
660
  color: Color;
661
  
662
  /** Diffuse texture */
663
  map: Texture | null;
664
  
665
  /** Lightmap texture */
666
  lightMap: Texture | null;
667
  
668
  /** Lightmap intensity */
669
  lightMapIntensity: number;
670
  
671
  /** Ambient occlusion map */
672
  aoMap: Texture | null;
673
  
674
  /** AO intensity */
675
  aoMapIntensity: number;
676
  
677
  /** Emissive color */
678
  emissive: Color;
679
  
680
  /** Emissive intensity */
681
  emissiveIntensity: number;
682
  
683
  /** Emissive texture */
684
  emissiveMap: Texture | null;
685
  
686
  /** Specular map */
687
  specularMap: Texture | null;
688
  
689
  /** Alpha map */
690
  alphaMap: Texture | null;
691
  
692
  /** Environment map */
693
  envMap: Texture | null;
694
  
695
  /** Environment map rotation */
696
  envMapRotation: Euler;
697
  
698
  /** Environment map intensity */
699
  envMapIntensity: number;
700
  
701
  /** Combine mode */
702
  combine: Combine;
703
  
704
  /** Reflectivity */
705
  reflectivity: number;
706
  
707
  /** Refraction ratio */
708
  refractionRatio: number;
709
  
710
  /** Wireframe mode */
711
  wireframe: boolean;
712
  
713
  /** Wireframe line width */
714
  wireframeLinewidth: number;
715
  
716
  /** Wireframe line cap */
717
  wireframeLinecap: string;
718
  
719
  /** Wireframe line join */
720
  wireframeLinejoin: string;
721
  
722
  /**
723
   * Create Lambert material
724
   * @param parameters - Material parameters
725
   */
726
  constructor(parameters?: Partial<MeshLambertMaterial>);
727
}
728

729
/**
730
 * Phong material with specular highlights
731
 */
732
class MeshPhongMaterial extends Material {
733
  /** Type flag for Phong material detection */
734
  readonly isMeshPhongMaterial: true;
735
  
736
  /** Diffuse color */
737
  color: Color;
738
  
739
  /** Specular color */
740
  specular: Color;
741
  
742
  /** Specular shininess */
743
  shininess: number;
744
  
745
  /** Diffuse texture */
746
  map: Texture | null;
747
  
748
  /** Lightmap texture */
749
  lightMap: Texture | null;
750
  
751
  /** Lightmap intensity */
752
  lightMapIntensity: number;
753
  
754
  /** Ambient occlusion map */
755
  aoMap: Texture | null;
756
  
757
  /** AO intensity */
758
  aoMapIntensity: number;
759
  
760
  /** Emissive color */
761
  emissive: Color;
762
  
763
  /** Emissive intensity */
764
  emissiveIntensity: number;
765
  
766
  /** Emissive texture */
767
  emissiveMap: Texture | null;
768
  
769
  /** Bump map */
770
  bumpMap: Texture | null;
771
  
772
  /** Bump scale */
773
  bumpScale: number;
774
  
775
  /** Normal map */
776
  normalMap: Texture | null;
777
  
778
  /** Normal map type */
779
  normalMapType: NormalMapType;
780
  
781
  /** Normal map scale */
782
  normalScale: Vector2;
783
  
784
  /** Displacement map */
785
  displacementMap: Texture | null;
786
  
787
  /** Displacement scale */
788
  displacementScale: number;
789
  
790
  /** Displacement bias */
791
  displacementBias: number;
792
  
793
  /** Specular map */
794
  specularMap: Texture | null;
795
  
796
  /** Alpha map */
797
  alphaMap: Texture | null;
798
  
799
  /** Environment map */
800
  envMap: Texture | null;
801
  
802
  /** Environment map rotation */
803
  envMapRotation: Euler;
804
  
805
  /** Environment map intensity */
806
  envMapIntensity: number;
807
  
808
  /** Combine mode */
809
  combine: Combine;
810
  
811
  /** Reflectivity */
812
  reflectivity: number;
813
  
814
  /** Refraction ratio */
815
  refractionRatio: number;
816
  
817
  /** Wireframe mode */
818
  wireframe: boolean;
819
  
820
  /** Flat shading */
821
  flatShading: boolean;
822
  
823
  /**
824
   * Create Phong material
825
   * @param parameters - Material parameters
826
   */
827
  constructor(parameters?: Partial<MeshPhongMaterial>);
828
}
829

830
/**
831
 * Toon/cartoon shading material
832
 */
833
class MeshToonMaterial extends Material {
834
  /** Type flag for toon material detection */
835
  readonly isMeshToonMaterial: true;
836
  
837
  /** Diffuse color */
838
  color: Color;
839
  
840
  /** Diffuse texture */
841
  map: Texture | null;
842
  
843
  /** Gradient map for toon shading */
844
  gradientMap: Texture | null;
845
  
846
  /** Lightmap texture */
847
  lightMap: Texture | null;
848
  
849
  /** Lightmap intensity */
850
  lightMapIntensity: number;
851
  
852
  /** Ambient occlusion map */
853
  aoMap: Texture | null;
854
  
855
  /** AO intensity */
856
  aoMapIntensity: number;
857
  
858
  /** Emissive color */
859
  emissive: Color;
860
  
861
  /** Emissive intensity */
862
  emissiveIntensity: number;
863
  
864
  /** Emissive texture */
865
  emissiveMap: Texture | null;
866
  
867
  /** Bump map */
868
  bumpMap: Texture | null;
869
  
870
  /** Bump scale */
871
  bumpScale: number;
872
  
873
  /** Normal map */
874
  normalMap: Texture | null;
875
  
876
  /** Normal map type */
877
  normalMapType: NormalMapType;
878
  
879
  /** Normal map scale */
880
  normalScale: Vector2;
881
  
882
  /** Displacement map */
883
  displacementMap: Texture | null;
884
  
885
  /** Displacement scale */
886
  displacementScale: number;
887
  
888
  /** Displacement bias */
889
  displacementBias: number;
890
  
891
  /** Alpha map */
892
  alphaMap: Texture | null;
893
  
894
  /** Wireframe mode */
895
  wireframe: boolean;
896
  
897
  /**
898
   * Create toon material
899
   * @param parameters - Material parameters
900
   */
901
  constructor(parameters?: Partial<MeshToonMaterial>);
902
}
903

904
/**
905
 * Material displaying surface normals as colors
906
 */
907
class MeshNormalMaterial extends Material {
908
  /** Type flag for normal material detection */
909
  readonly isMeshNormalMaterial: true;
910
  
911
  /** Bump map */
912
  bumpMap: Texture | null;
913
  
914
  /** Bump scale */
915
  bumpScale: number;
916
  
917
  /** Normal map */
918
  normalMap: Texture | null;
919
  
920
  /** Normal map type */
921
  normalMapType: NormalMapType;
922
  
923
  /** Normal map scale */
924
  normalScale: Vector2;
925
  
926
  /** Displacement map */
927
  displacementMap: Texture | null;
928
  
929
  /** Displacement scale */
930
  displacementScale: number;
931
  
932
  /** Displacement bias */
933
  displacementBias: number;
934
  
935
  /** Wireframe mode */
936
  wireframe: boolean;
937
  
938
  /** Flat shading */
939
  flatShading: boolean;
940
  
941
  /**
942
   * Create normal material
943
   * @param parameters - Material parameters
944
   */
945
  constructor(parameters?: Partial<MeshNormalMaterial>);
946
}
947

948
/**
949
 * Matcap material using spherical environment mapping
950
 */
951
class MeshMatcapMaterial extends Material {
952
  /** Type flag for matcap material detection */
953
  readonly isMeshMatcapMaterial: true;
954
  
955
  /** Base color */
956
  color: Color;
957
  
958
  /** Matcap texture (spherical environment map) */
959
  matcap: Texture | null;
960
  
961
  /** Color texture */
962
  map: Texture | null;
963
  
964
  /** Bump map */
965
  bumpMap: Texture | null;
966
  
967
  /** Bump scale */
968
  bumpScale: number;
969
  
970
  /** Normal map */
971
  normalMap: Texture | null;
972
  
973
  /** Normal map type */
974
  normalMapType: NormalMapType;
975
  
976
  /** Normal map scale */
977
  normalScale: Vector2;
978
  
979
  /** Displacement map */
980
  displacementMap: Texture | null;
981
  
982
  /** Displacement scale */
983
  displacementScale: number;
984
  
985
  /** Displacement bias */
986
  displacementBias: number;
987
  
988
  /** Alpha map */
989
  alphaMap: Texture | null;
990
  
991
  /** Flat shading */
992
  flatShading: boolean;
993
  
994
  /**
995
   * Create matcap material
996
   * @param parameters - Material parameters
997
   */
998
  constructor(parameters?: Partial<MeshMatcapMaterial>);
999
}
1000
```
1001

1002
**Usage Examples:**
1003

1004
```typescript
1005
import { 
1006
  MeshBasicMaterial, 
1007
  MeshLambertMaterial,
1008
  MeshPhongMaterial,
1009
  MeshToonMaterial,
1010
  MeshNormalMaterial,
1011
  Color
1012
} from 'three';
1013

1014
// Unlit basic material
1015
const basic = new MeshBasicMaterial({
1016
  color: 0xff0000,
1017
  wireframe: true
1018
});
1019

1020
// Simple diffuse lighting
1021
const lambert = new MeshLambertMaterial({
1022
  color: 0x00ff00
1023
});
1024

1025
// Phong with specular highlights
1026
const phong = new MeshPhongMaterial({
1027
  color: 0x0000ff,
1028
  specular: new Color(0x222222),
1029
  shininess: 100
1030
});
1031

1032
// Cartoon/anime style
1033
const toon = new MeshToonMaterial({
1034
  color: 0xffaa00
1035
});
1036

1037
// Debug normals
1038
const normal = new MeshNormalMaterial();
1039

1040
// Matcap for stylized look
1041
const matcap = new MeshMatcapMaterial({
1042
  matcap: matcapTexture
1043
});
1044
```
1045

1046
### Line and Point Materials
1047

1048
Specialized materials for line rendering and point clouds with custom styling options.
1049

1050
```typescript { .api }
1051
import { 
1052
  LineBasicMaterial,
1053
  LineDashedMaterial,
1054
  PointsMaterial,
1055
  SpriteMaterial
1056
} from 'three';
1057

1058
/**
1059
 * Basic line material
1060
 */
1061
class LineBasicMaterial extends Material {
1062
  /** Type flag for line basic material detection */
1063
  readonly isLineBasicMaterial: true;
1064
  
1065
  /** Line color */
1066
  color: Color;
1067
  
1068
  /** Line width (limited platform support) */
1069
  linewidth: number;
1070
  
1071
  /** Line cap style */
1072
  linecap: string;
1073
  
1074
  /** Line join style */
1075
  linejoin: string;
1076
  
1077
  /**
1078
   * Create basic line material
1079
   * @param parameters - Material parameters
1080
   */
1081
  constructor(parameters?: Partial<LineBasicMaterial>);
1082
}
1083

1084
/**
1085
 * Dashed line material
1086
 */
1087
class LineDashedMaterial extends LineBasicMaterial {
1088
  /** Type flag for dashed material detection */
1089
  readonly isLineDashedMaterial: true;
1090
  
1091
  /** Dash scale */
1092
  scale: number;
1093
  
1094
  /** Dash size */
1095
  dashSize: number;
1096
  
1097
  /** Gap size */
1098
  gapSize: number;
1099
  
1100
  /**
1101
   * Create dashed line material
1102
   * @param parameters - Material parameters
1103
   */
1104
  constructor(parameters?: Partial<LineDashedMaterial>);
1105
}
1106

1107
/**
1108
 * Point cloud material
1109
 */
1110
class PointsMaterial extends Material {
1111
  /** Type flag for points material detection */
1112
  readonly isPointsMaterial: true;
1113
  
1114
  /** Point color */
1115
  color: Color;
1116
  
1117
  /** Point texture */
1118
  map: Texture | null;
1119
  
1120
  /** Alpha map */
1121
  alphaMap: Texture | null;
1122
  
1123
  /** Point size */
1124
  size: number;
1125
  
1126
  /** Size attenuation with distance */
1127
  sizeAttenuation: boolean;
1128
  
1129
  /**
1130
   * Create points material
1131
   * @param parameters - Material parameters
1132
   */
1133
  constructor(parameters?: Partial<PointsMaterial>);
1134
}
1135

1136
/**
1137
 * 2D sprite material (always faces camera)
1138
 */
1139
class SpriteMaterial extends Material {
1140
  /** Type flag for sprite material detection */
1141
  readonly isSpriteMaterial: true;
1142
  
1143
  /** Sprite color */
1144
  color: Color;
1145
  
1146
  /** Sprite texture */
1147
  map: Texture | null;
1148
  
1149
  /** Alpha map */
1150
  alphaMap: Texture | null;
1151
  
1152
  /** Sprite rotation */
1153
  rotation: number;
1154
  
1155
  /** Size attenuation */
1156
  sizeAttenuation: boolean;
1157
  
1158
  /**
1159
   * Create sprite material
1160
   * @param parameters - Material parameters
1161
   */
1162
  constructor(parameters?: Partial<SpriteMaterial>);
1163
}
1164
```
1165

1166
**Usage Examples:**
1167

1168
```typescript
1169
import { 
1170
  LineBasicMaterial, 
1171
  LineDashedMaterial,
1172
  PointsMaterial,
1173
  SpriteMaterial
1174
} from 'three';
1175

1176
// Basic line
1177
const line = new LineBasicMaterial({
1178
  color: 0xff0000,
1179
  linewidth: 2
1180
});
1181

1182
// Dashed line
1183
const dashed = new LineDashedMaterial({
1184
  color: 0x00ff00,
1185
  linewidth: 1,
1186
  scale: 1,
1187
  dashSize: 3,
1188
  gapSize: 1
1189
});
1190

1191
// Point cloud
1192
const points = new PointsMaterial({
1193
  color: 0x0000ff,
1194
  size: 5,
1195
  sizeAttenuation: true
1196
});
1197

1198
// Sprite/billboard
1199
const sprite = new SpriteMaterial({
1200
  map: texture,
1201
  color: 0xffffff
1202
});
1203
```
1204

1205
### Shader Materials
1206

1207
Custom shader materials for advanced effects and specialized rendering techniques.
1208

1209
```typescript { .api }
1210
import { 
1211
  ShaderMaterial,
1212
  RawShaderMaterial,
1213
  Material,
1214
  IUniform,
1215
  Shader
1216
} from 'three';
1217

1218
/**
1219
 * Custom shader material with Three.js uniforms
1220
 */
1221
class ShaderMaterial extends Material {
1222
  /** Type flag for shader material detection */
1223
  readonly isShaderMaterial: true;
1224
  
1225
  /** Shader defines */
1226
  defines: Record<string, any>;
1227
  
1228
  /** Shader uniforms */
1229
  uniforms: Record<string, IUniform>;
1230
  
1231
  /** Vertex shader source */
1232
  vertexShader: string;
1233
  
1234
  /** Fragment shader source */
1235
  fragmentShader: string;
1236
  
1237
  /** Line width */
1238
  linewidth: number;
1239
  
1240
  /** Wireframe mode */
1241
  wireframe: boolean;
1242
  
1243
  /** Wireframe line width */
1244
  wireframeLinewidth: number;
1245
  
1246
  /** Flat shading */
1247
  flatShading: boolean;
1248
  
1249
  /** Enable lights */
1250
  lights: boolean;
1251
  
1252
  /** Enable clipping */
1253
  clipping: boolean;
1254
  
1255
  /** Extensions */
1256
  extensions: {
1257
    derivatives?: boolean;
1258
    fragDepth?: boolean;
1259
    drawBuffers?: boolean;
1260
    shaderTextureLOD?: boolean;
1261
    clipCullDistance?: boolean;
1262
    multiDraw?: boolean;
1263
  };
1264
  
1265
  /** GL state overrides */
1266
  glslVersion?: string;
1267
  
1268
  /**
1269
   * Create shader material
1270
   * @param parameters - Material parameters including shaders and uniforms
1271
   */
1272
  constructor(parameters?: Partial<ShaderMaterial>);
1273
  
1274
  /**
1275
   * Clone shader material
1276
   * @returns Cloned material
1277
   */
1278
  clone(): this;
1279
  
1280
  /**
1281
   * Copy from another shader material
1282
   * @param source - Source material
1283
   * @returns This material for chaining
1284
   */
1285
  copy(source: ShaderMaterial): this;
1286
}
1287

1288
/**
1289
 * Raw shader material without Three.js built-in uniforms
1290
 */
1291
class RawShaderMaterial extends ShaderMaterial {
1292
  /** Type flag for raw shader material detection */
1293
  readonly isRawShaderMaterial: true;
1294
  
1295
  /**
1296
   * Create raw shader material
1297
   * @param parameters - Material parameters
1298
   */
1299
  constructor(parameters?: Partial<RawShaderMaterial>);
1300
}
1301

1302
/**
1303
 * Interface for uniform values
1304
 */
1305
interface IUniform<T = any> {
1306
  value: T;
1307
}
1308

1309
/**
1310
 * Shader compilation result
1311
 */
1312
interface Shader {
1313
  uniforms: Record<string, IUniform>;
1314
  vertexShader: string;
1315
  fragmentShader: string;
1316
  defines?: Record<string, any>;
1317
}
1318
```
1319

1320
**Usage Examples:**
1321

1322
```typescript
1323
import { ShaderMaterial, RawShaderMaterial, Vector3, Color } from 'three';
1324

1325
// Custom shader material
1326
const customMaterial = new ShaderMaterial({
1327
  uniforms: {
1328
    time: { value: 0 },
1329
    color: { value: new Color(0xff0000) },
1330
    resolution: { value: new Vector3(1024, 768, 1) }
1331
  },
1332
  vertexShader: `
1333
    void main() {
1334
      gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
1335
    }
1336
  `,
1337
  fragmentShader: `
1338
    uniform float time;
1339
    uniform vec3 color;
1340
    uniform vec3 resolution;
1341
    
1342
    void main() {
1343
      vec2 uv = gl_FragCoord.xy / resolution.xy;
1344
      vec3 col = color * (sin(time + uv.x * 10.0) * 0.5 + 0.5);
1345
      gl_FragColor = vec4(col, 1.0);
1346
    }
1347
  `,
1348
  transparent: true
1349
});
1350

1351
// Raw shader (no Three.js uniforms)
1352
const rawMaterial = new RawShaderMaterial({
1353
  uniforms: {
1354
    mvpMatrix: { value: new Matrix4() }
1355
  },
1356
  vertexShader: `
1357
    precision mediump float;
1358
    uniform mat4 mvpMatrix;
1359
    attribute vec3 position;
1360
    
1361
    void main() {
1362
      gl_Position = mvpMatrix * vec4(position, 1.0);
1363
    }
1364
  `,
1365
  fragmentShader: `
1366
    precision mediump float;
1367
    
1368
    void main() {
1369
      gl_FragColor = vec4(1.0, 0.0, 0.0, 1.0);
1370
    }
1371
  `
1372
});
1373

1374
// Update uniforms in render loop
1375
function animate() {
1376
  customMaterial.uniforms.time.value = performance.now() / 1000;
1377
  renderer.render(scene, camera);
1378
  requestAnimationFrame(animate);
1379
}
1380
```
1381

1382
### Special Materials
1383

1384
Utility materials for debugging, shadows, and special rendering effects.
1385

1386
```typescript { .api }
1387
import { 
1388
  MeshDepthMaterial,
1389
  MeshDistanceMaterial, 
1390
  ShadowMaterial
1391
} from 'three';
1392

1393
/**
1394
 * Material for rendering depth values
1395
 */
1396
class MeshDepthMaterial extends Material {
1397
  /** Type flag for depth material detection */
1398
  readonly isMeshDepthMaterial: true;
1399
  
1400
  /** Depth packing type */
1401
  depthPacking: DepthPackingStrategies;
1402
  
1403
  /** Displacement map */
1404
  displacementMap: Texture | null;
1405
  
1406
  /** Displacement scale */
1407
  displacementScale: number;
1408
  
1409
  /** Displacement bias */
1410
  displacementBias: number;
1411
  
1412
  /** Alpha map */
1413
  alphaMap: Texture | null;
1414
  
1415
  /** Wireframe mode */
1416
  wireframe: boolean;
1417
  
1418
  /**
1419
   * Create depth material
1420
   * @param parameters - Material parameters
1421
   */
1422
  constructor(parameters?: Partial<MeshDepthMaterial>);
1423
}
1424

1425
/**
1426
 * Material for rendering distance from point
1427
 */
1428
class MeshDistanceMaterial extends Material {
1429
  /** Type flag for distance material detection */
1430
  readonly isMeshDistanceMaterial: true;
1431
  
1432
  /** Reference position for distance calculation */
1433
  referencePosition: Vector3;
1434
  
1435
  /** Near distance */
1436
  nearDistance: number;
1437
  
1438
  /** Far distance */
1439
  farDistance: number;
1440
  
1441
  /** Displacement map */
1442
  displacementMap: Texture | null;
1443
  
1444
  /** Displacement scale */
1445
  displacementScale: number;
1446
  
1447
  /** Displacement bias */
1448
  displacementBias: number;
1449
  
1450
  /** Alpha map */
1451
  alphaMap: Texture | null;
1452
  
1453
  /**
1454
   * Create distance material
1455
   * @param parameters - Material parameters
1456
   */
1457
  constructor(parameters?: Partial<MeshDistanceMaterial>);
1458
}
1459

1460
/**
1461
 * Material that only renders shadows (transparent otherwise)
1462
 */
1463
class ShadowMaterial extends Material {
1464
  /** Type flag for shadow material detection */
1465
  readonly isShadowMaterial: true;
1466
  
1467
  /** Shadow color */
1468
  color: Color;
1469
  
1470
  /**
1471
   * Create shadow material
1472
   * @param parameters - Material parameters
1473
   */
1474
  constructor(parameters?: Partial<ShadowMaterial>);
1475
}
1476
```
1477

1478
**Usage Examples:**
1479

1480
```typescript
1481
import { 
1482
  MeshDepthMaterial,
1483
  ShadowMaterial,
1484
  RGBADepthPacking
1485
} from 'three';
1486

1487
// Depth material for depth buffer visualization
1488
const depthMaterial = new MeshDepthMaterial({
1489
  depthPacking: RGBADepthPacking
1490
});
1491

1492
// Shadow catcher material
1493
const shadowCatcher = new ShadowMaterial({
1494
  color: new Color(0x000000),
1495
  opacity: 0.5,
1496
  transparent: true
1497
});
1498

1499
// Apply to ground plane to catch shadows
1500
groundPlane.material = shadowCatcher;
1501
```
1502

1503
The material system provides comprehensive surface appearance control through physically-based rendering, artistic shading models, and custom shader support. Materials define how surfaces interact with light and determine the final rendered appearance of 3D objects.