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>
three-types · Jul 18, 2024 · 12a22f8 · 12a22f8
1 parent b72e5c5
commit 12a22f8
Show file tree

Hide file tree

Showing 3 changed files with 215 additions and 6 deletions.
diff --git a/types/three/src/core/Object3D.d.ts b/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>;

diff --git a/types/three/src/materials/Material.d.ts b/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.

diff --git a/types/three/src/materials/ShaderMaterial.d.ts b/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;
 }