Update Material type definitions: Add MaterialJSON format (#1072)

* Update Material type definitions: Add MaterialJSON format

Introduces the MaterialJSON format in Three.js, which extends the Material interface. The new format includes serializable properties such as color, roughness, metallic, map, normalMap, and many more. This change enables better JSON parsing and handling of material configurations for Three.js applications.

Confirmed: Types and interfaces have been updated in Object3D.d.ts and Material.d.ts. The Material class has also been updated to include toJSON methods that return MaterialJSON or MaterialJSONRoot objects based on the provided meta data.

Reference(s):
#1071
#1070
#426

* Fix: Error:   240:16  error  Array type using 'T[]' is forbidden for non-simple types. Use 'Array<T>' instead  @typescript-eslint/array-type

* ShaderMaterial & Fixes

* Add ShaderMaterialJSON to JSONMeta.materials record

* Fixes
Error:   105:28  error  Array type using 'Array<number>' is forbidden for simple types. Use 'number[]' instead          @typescript-eslint/array-type
Error:   136:19  error  Array type using 'Array<number>' is forbidden for simple types. Use 'number[]' instead          @typescript-eslint/array-type
Error:   157:22  error  Array type using 'Array<number>' is forbidden for simple types. Use 'number[]' instead          @typescript-eslint/array-type
Error:   242:14  error  Array type using 'Array<SourceJSON>' is forbidden for simple types. Use 'SourceJSON[]' instead  @typescript-eslint/array-type

* Error:   240:16  error  Array type using 'T[]' is forbidden for non-simple types. Use 'Array<T>' instead  @typescript-eslint/array-type

* Material

* ShaderMaterial

* Object3D

---------

Co-authored-by: Nathan Bierema <nbierema@gmail.com>

Author: Hoodgail

types/three/src/core/Object3D.d.ts

@@ -1,6 +1,6 @@
 import { AnimationClip, AnimationClipJSON } from "../animation/AnimationClip.js";
 import { Camera } from "../cameras/Camera.js";
-import { Material } from "../materials/Material.js";
+import { Material, MaterialJSON } from "../materials/Material.js";
 import { Euler } from "../math/Euler.js";
 import { Matrix3 } from "../math/Matrix3.js";
 import { Matrix4, Matrix4Tuple } from "../math/Matrix4.js";
@@ -49,7 +49,7 @@ export interface Object3DJSON {
 
 export interface JSONMeta {
     geometries: Record<string, BufferGeometryJSON>;
-    materials: Record<string, unknown>;
+    materials: Record<string, MaterialJSON>;
     textures: Record<string, TextureJSON>;
     images: Record<string, SourceJSON>;
     shapes: Record<string, unknown>;

types/three/src/materials/Material.d.ts

@@ -4,21 +4,24 @@ import {
     BlendingDstFactor,
     BlendingEquation,
     BlendingSrcFactor,
+    Combine,
     DepthModes,
+    NormalMapTypes,
     PixelFormat,
     Side,
     StencilFunc,
     StencilOp,
 } from "../constants.js";
 import { BufferGeometry } from "../core/BufferGeometry.js";
 import { EventDispatcher } from "../core/EventDispatcher.js";
-import { Object3D } from "../core/Object3D.js";
+import { JSONMeta, Object3D } from "../core/Object3D.js";
 import { Color, ColorRepresentation } from "../math/Color.js";
 import { Plane } from "../math/Plane.js";
 import { Group } from "../objects/Group.js";
 import { WebGLProgramParametersWithUniforms } from "../renderers/webgl/WebGLPrograms.js";
 import { WebGLRenderer } from "../renderers/WebGLRenderer.js";
 import { Scene } from "../scenes/Scene.js";
+import { EulerTuple, SourceJSON, TextureJSON, Vector2Tuple } from "../Three.js";
 
 export interface MaterialParameters {
     alphaHash?: boolean | undefined;
@@ -68,6 +71,165 @@ export interface MaterialParameters {
     userData?: Record<string, any> | undefined;
 }
 
+export interface MaterialJSON {
+    metadata: { version: number; type: string; generator: string };
+
+    uuid: string;
+    type: string;
+
+    name?: string;
+
+    color?: number;
+    roughness?: number;
+    metalness?: number;
+
+    sheen?: number;
+    sheenColor?: number;
+    sheenRoughness?: number;
+    emissive?: number;
+    emissiveIntensity?: number;
+
+    specular?: number;
+    specularIntensity?: number;
+    specularColor?: number;
+    shininess?: number;
+    clearcoat?: number;
+    clearcoatRoughness?: number;
+    clearcoatMap?: string;
+    clearcoatRoughnessMap?: string;
+    clearcoatNormalMap?: string;
+    clearcoatNormalScale?: Vector2Tuple;
+
+    dispersion?: number;
+
+    iridescence?: number;
+    iridescenceIOR?: number;
+    iridescenceThicknessRange?: number;
+    iridescenceMap?: string;
+    iridescenceThicknessMap?: string;
+
+    anisotropy?: number;
+    anisotropyRotation?: number;
+    anisotropyMap?: string;
+
+    map?: string;
+    matcap?: string;
+    alphaMap?: string;
+
+    lightMap?: string;
+    lightMapIntensity?: number;
+
+    aoMap?: string;
+    aoMapIntensity?: number;
+
+    bumpMap?: string;
+    bumpScale?: number;
+
+    normalMap?: string;
+    normalMapType?: NormalMapTypes;
+    normalScale?: Vector2Tuple;
+
+    displacementMap?: string;
+    displacementScale?: number;
+    displacementBias?: number;
+
+    roughnessMap?: string;
+    metalnessMap?: string;
+
+    emissiveMap?: string;
+    specularMap?: string;
+    specularIntensityMap?: string;
+    specularColorMap?: string;
+
+    envMap?: string;
+    combine?: Combine;
+
+    envMapRotation?: EulerTuple;
+    envMapIntensity?: number;
+    reflectivity?: number;
+    refractionRatio?: number;
+
+    gradientMap?: string;
+
+    transmission?: number;
+    transmissionMap?: string;
+    thickness?: number;
+    thicknessMap?: string;
+    attenuationDistance?: number;
+    attenuationColor?: number;
+
+    size?: number;
+    shadowSide?: number;
+    sizeAttenuation?: boolean;
+
+    blending?: Blending;
+    side?: Side;
+    vertexColors?: boolean;
+
+    opacity?: number;
+    transparent?: boolean;
+
+    blendSrc?: BlendingSrcFactor;
+    blendDst?: BlendingDstFactor;
+    blendEquation?: BlendingEquation;
+    blendSrcAlpha?: number | null;
+    blendDstAlpha?: number | null;
+    blendEquationAlpha?: number | null;
+    blendColor?: number;
+    blendAlpha?: number;
+
+    depthFunc?: DepthModes;
+    depthTest?: boolean;
+    depthWrite?: boolean;
+    colorWrite?: boolean;
+
+    stencilWriteMask?: number;
+    stencilFunc?: StencilFunc;
+    stencilRef?: number;
+    stencilFuncMask?: number;
+    stencilFail?: StencilOp;
+    stencilZFail?: StencilOp;
+    stencilZPass?: StencilOp;
+    stencilWrite?: boolean;
+
+    rotation?: number;
+
+    polygonOffset?: boolean;
+    polygonOffsetFactor?: number;
+    polygonOffsetUnits?: number;
+
+    linewidth?: number;
+    dashSize?: number;
+    gapSize?: number;
+    scale?: number;
+
+    dithering?: boolean;
+
+    alphaTest?: number;
+    alphaHash?: boolean;
+    alphaToCoverage?: boolean;
+    premultipliedAlpha?: boolean;
+    forceSinglePass?: boolean;
+
+    wireframe?: boolean;
+    wireframeLinewidth?: number;
+    wireframeLinecap?: string;
+    wireframeLinejoin?: string;
+
+    flatShading?: boolean;
+
+    visible?: boolean;
+
+    toneMapped?: boolean;
+
+    fog?: boolean;
+
+    userData?: Record<string, unknown>;
+
+    textures?: Array<Omit<TextureJSON, "metadata">>;
+    images?: SourceJSON[];
+}
+
 /**
  * Materials describe the appearance of objects. They are defined in a (mostly) renderer-independent way, so you don't have to rewrite materials if you decide to use a different renderer.
  */
@@ -418,7 +580,7 @@ export class Material extends EventDispatcher<{ dispose: {} }> {
      * Convert the material to three.js JSON format.
      * @param meta Object containing metadata such as textures or images for the material.
      */
-    toJSON(meta?: any): any;
+    toJSON(meta?: JSONMeta): MaterialJSON;
 
     /**
      * Return a new material with the same parameters as this material.

types/three/src/materials/ShaderMaterial.d.ts

@@ -1,7 +1,13 @@
 import { GLSLVersion } from "../constants.js";
+import { JSONMeta } from "../core/Object3D.js";
 import { UniformsGroup } from "../core/UniformsGroup.js";
+import { Matrix3, Matrix3Tuple } from "../math/Matrix3.js";
+import { Matrix4, Matrix4Tuple } from "../math/Matrix4.js";
+import { Vector2Tuple } from "../math/Vector2.js";
+import { Vector3Tuple } from "../math/Vector3.js";
+import { Vector4Tuple } from "../math/Vector4.js";
 import { IUniform } from "../renderers/shaders/UniformsLib.js";
-import { Material, MaterialParameters } from "./Material.js";
+import { Material, MaterialJSON, MaterialParameters } from "./Material.js";
 
 export interface ShaderMaterialParameters extends MaterialParameters {
     uniforms?: { [uniform: string]: IUniform } | undefined;
@@ -23,6 +29,46 @@ export interface ShaderMaterialParameters extends MaterialParameters {
     glslVersion?: GLSLVersion | undefined;
 }
 
+export type ShaderMaterialUniformJSON = {
+    type: "t";
+    value: string;
+} | {
+    type: "c";
+    value: number;
+} | {
+    type: "v2";
+    value: Vector2Tuple;
+} | {
+    type: "v3";
+    value: Vector3Tuple;
+} | {
+    type: "v4";
+    value: Vector4Tuple;
+} | {
+    type: "m3";
+    value: Matrix3Tuple;
+} | {
+    type: "m4";
+    value: Matrix4Tuple;
+} | {
+    value: unknown;
+};
+
+export interface ShaderMaterialJSON extends MaterialJSON {
+    glslVersion: number | null;
+    uniforms: Record<string, ShaderMaterialUniformJSON>;
+
+    defines?: Record<string, unknown>;
+
+    vertexShader: string;
+    ragmentShader: string;
+
+    lights: boolean;
+    clipping: boolean;
+
+    extensions?: Record<string, boolean>;
+}
+
 export class ShaderMaterial extends Material {
     constructor(parameters?: ShaderMaterialParameters);
 
@@ -116,5 +162,6 @@ export class ShaderMaterial extends Material {
     glslVersion: GLSLVersion | null;
 
     setValues(parameters: ShaderMaterialParameters): void;
-    toJSON(meta: any): any;
+
+    toJSON(meta?: JSONMeta): ShaderMaterialJSON;
 }