@flighthq/materials 0.1.0

package/src/materialValidation.test.ts

@@ -0,0 +1,130 @@
+import {
+  clampStandardPbrMaterialProperties,
+  isValidMaterialClearcoat,
+  isValidMaterialIor,
+  isValidMaterialIridescenceThickness,
+  isValidMaterialWeight,
+} from './materialValidation';
+import { createStandardPbrMaterialProperties } from './pbrMaterials';
+
+describe('clampStandardPbrMaterialProperties', () => {
+  it('returns the out instance', () => {
+    const props = createStandardPbrMaterialProperties();
+    expect(clampStandardPbrMaterialProperties(props)).toBe(props);
+  });
+  it('clamps metallic to [0, 1]', () => {
+    const props = createStandardPbrMaterialProperties({ metallic: 1.5 });
+    clampStandardPbrMaterialProperties(props);
+    expect(props.metallic).toBe(1);
+    props.metallic = -0.5;
+    clampStandardPbrMaterialProperties(props);
+    expect(props.metallic).toBe(0);
+  });
+  it('clamps roughness to [0, 1]', () => {
+    const props = createStandardPbrMaterialProperties({ roughness: 2 });
+    clampStandardPbrMaterialProperties(props);
+    expect(props.roughness).toBe(1);
+    props.roughness = -1;
+    clampStandardPbrMaterialProperties(props);
+    expect(props.roughness).toBe(0);
+  });
+  it('clamps occlusionStrength to [0, 1]', () => {
+    const props = createStandardPbrMaterialProperties({ occlusionStrength: 3 });
+    clampStandardPbrMaterialProperties(props);
+    expect(props.occlusionStrength).toBe(1);
+    props.occlusionStrength = -1;
+    clampStandardPbrMaterialProperties(props);
+    expect(props.occlusionStrength).toBe(0);
+  });
+  it('clamps emissiveStrength to [0, ∞) — allows values above 1 for HDR emissive', () => {
+    const props = createStandardPbrMaterialProperties({ emissiveStrength: -1 });
+    clampStandardPbrMaterialProperties(props);
+    expect(props.emissiveStrength).toBe(0);
+    props.emissiveStrength = 10;
+    clampStandardPbrMaterialProperties(props);
+    expect(props.emissiveStrength).toBe(10);
+  });
+  it('clamps normalScale to [0, ∞) — allows values above 1 for exaggerated normals', () => {
+    const props = createStandardPbrMaterialProperties({ normalScale: -2 });
+    clampStandardPbrMaterialProperties(props);
+    expect(props.normalScale).toBe(0);
+    props.normalScale = 5;
+    clampStandardPbrMaterialProperties(props);
+    expect(props.normalScale).toBe(5);
+  });
+  it('leaves a valid block unchanged', () => {
+    const props = createStandardPbrMaterialProperties({ metallic: 0.5, roughness: 0.3 });
+    clampStandardPbrMaterialProperties(props);
+    expect(props.metallic).toBe(0.5);
+    expect(props.roughness).toBe(0.3);
+  });
+});
+
+describe('isValidMaterialClearcoat', () => {
+  it('returns true for values in [0, 1]', () => {
+    expect(isValidMaterialClearcoat(0)).toBe(true);
+    expect(isValidMaterialClearcoat(0.5)).toBe(true);
+    expect(isValidMaterialClearcoat(1)).toBe(true);
+  });
+  it('returns false for values outside [0, 1]', () => {
+    expect(isValidMaterialClearcoat(-0.1)).toBe(false);
+    expect(isValidMaterialClearcoat(1.1)).toBe(false);
+  });
+  it('returns false for NaN and Infinity', () => {
+    expect(isValidMaterialClearcoat(NaN)).toBe(false);
+    expect(isValidMaterialClearcoat(Infinity)).toBe(false);
+  });
+});
+
+describe('isValidMaterialIor', () => {
+  it('returns true for valid IOR values', () => {
+    expect(isValidMaterialIor(1.0)).toBe(true);
+    expect(isValidMaterialIor(1.5)).toBe(true);
+    expect(isValidMaterialIor(2.4)).toBe(true);
+    expect(isValidMaterialIor(5.0)).toBe(true);
+  });
+  it('returns false for IOR below 1', () => {
+    expect(isValidMaterialIor(0.9)).toBe(false);
+    expect(isValidMaterialIor(0)).toBe(false);
+  });
+  it('returns false for IOR above 5', () => {
+    expect(isValidMaterialIor(5.1)).toBe(false);
+    expect(isValidMaterialIor(100)).toBe(false);
+  });
+  it('returns false for NaN and Infinity', () => {
+    expect(isValidMaterialIor(NaN)).toBe(false);
+    expect(isValidMaterialIor(Infinity)).toBe(false);
+  });
+});
+
+describe('isValidMaterialIridescenceThickness', () => {
+  it('returns true for non-negative finite values', () => {
+    expect(isValidMaterialIridescenceThickness(0)).toBe(true);
+    expect(isValidMaterialIridescenceThickness(100)).toBe(true);
+    expect(isValidMaterialIridescenceThickness(400)).toBe(true);
+    expect(isValidMaterialIridescenceThickness(2000)).toBe(true);
+  });
+  it('returns false for negative values', () => {
+    expect(isValidMaterialIridescenceThickness(-1)).toBe(false);
+  });
+  it('returns false for NaN and Infinity', () => {
+    expect(isValidMaterialIridescenceThickness(NaN)).toBe(false);
+    expect(isValidMaterialIridescenceThickness(Infinity)).toBe(false);
+  });
+});
+
+describe('isValidMaterialWeight', () => {
+  it('returns true for values in [0, 1]', () => {
+    expect(isValidMaterialWeight(0)).toBe(true);
+    expect(isValidMaterialWeight(0.5)).toBe(true);
+    expect(isValidMaterialWeight(1)).toBe(true);
+  });
+  it('returns false for values outside [0, 1]', () => {
+    expect(isValidMaterialWeight(-0.001)).toBe(false);
+    expect(isValidMaterialWeight(1.001)).toBe(false);
+  });
+  it('returns false for NaN and Infinity', () => {
+    expect(isValidMaterialWeight(NaN)).toBe(false);
+    expect(isValidMaterialWeight(Infinity)).toBe(false);
+  });
+});

package/src/pbrExtensionMaterials.test.ts

@@ -0,0 +1,123 @@
+import {
+  AnisotropyPbrMaterialKind,
+  ClearcoatPbrMaterialKind,
+  IridescencePbrMaterialKind,
+  SheenPbrMaterialKind,
+  SpecularPbrMaterialKind,
+  SubsurfacePbrMaterialKind,
+  TransmissionVolumePbrMaterialKind,
+} from '@flighthq/types';
+
+import {
+  createAnisotropyPbrMaterial,
+  createClearcoatPbrMaterial,
+  createIridescencePbrMaterial,
+  createSheenPbrMaterial,
+  createSpecularPbrMaterial,
+  createSubsurfacePbrMaterial,
+  createTransmissionVolumePbrMaterial,
+} from './pbrExtensionMaterials';
+import { createStandardPbrMaterialProperties } from './pbrMaterials';
+
+describe('createAnisotropyPbrMaterial', () => {
+  it('creates an isotropic anisotropy material with a default standard block', () => {
+    const material = createAnisotropyPbrMaterial();
+    expect(material.kind).toBe(AnisotropyPbrMaterialKind);
+    expect(material.anisotropyStrength).toBe(0);
+    expect(material.anisotropyRotation).toBe(0);
+    expect(material.standard.baseColor).toBe(0xffffffff);
+  });
+
+  it('composes a provided standard block', () => {
+    const standard = createStandardPbrMaterialProperties({ metallic: 1 });
+    expect(createAnisotropyPbrMaterial({ standard }).standard).toBe(standard);
+  });
+});
+
+describe('createClearcoatPbrMaterial', () => {
+  it('creates a disabled clearcoat material with a default standard block', () => {
+    const material = createClearcoatPbrMaterial();
+    expect(material.kind).toBe(ClearcoatPbrMaterialKind);
+    expect(material.clearcoat).toBe(0);
+    expect(material.clearcoatRoughness).toBe(0);
+    expect(material.standard.roughness).toBe(1);
+  });
+
+  it('applies overrides', () => {
+    expect(createClearcoatPbrMaterial({ clearcoat: 1 }).clearcoat).toBe(1);
+  });
+});
+
+describe('createIridescencePbrMaterial', () => {
+  it('creates a disabled iridescence material with glTF thickness defaults', () => {
+    const material = createIridescencePbrMaterial();
+    expect(material.kind).toBe(IridescencePbrMaterialKind);
+    expect(material.iridescence).toBe(0);
+    expect(material.iridescenceIor).toBe(1.3);
+    expect(material.iridescenceThicknessMin).toBe(100);
+    expect(material.iridescenceThicknessMax).toBe(400);
+  });
+
+  it('applies overrides', () => {
+    expect(createIridescencePbrMaterial({ iridescence: 1 }).iridescence).toBe(1);
+  });
+});
+
+describe('createSheenPbrMaterial', () => {
+  it('creates a disabled sheen material with a default standard block', () => {
+    const material = createSheenPbrMaterial();
+    expect(material.kind).toBe(SheenPbrMaterialKind);
+    expect(material.sheenColor).toBe(0x000000ff);
+    expect(material.sheenRoughness).toBe(0);
+    expect(material.standard.baseColor).toBe(0xffffffff);
+  });
+
+  it('applies overrides', () => {
+    expect(createSheenPbrMaterial({ sheenColor: 0xffffffff }).sheenColor).toBe(0xffffffff);
+  });
+});
+
+describe('createSpecularPbrMaterial', () => {
+  it('creates a full-specular white-tint material with a default standard block', () => {
+    const material = createSpecularPbrMaterial();
+    expect(material.kind).toBe(SpecularPbrMaterialKind);
+    expect(material.specular).toBe(1);
+    expect(material.specularColor).toBe(0xffffffff);
+    expect(material.standard.metallic).toBe(0);
+  });
+
+  it('applies overrides', () => {
+    expect(createSpecularPbrMaterial({ specular: 0.5 }).specular).toBe(0.5);
+  });
+});
+
+describe('createSubsurfacePbrMaterial', () => {
+  it('creates a disabled subsurface material with a default standard block', () => {
+    const material = createSubsurfacePbrMaterial();
+    expect(material.kind).toBe(SubsurfacePbrMaterialKind);
+    expect(material.subsurface).toBe(0);
+    expect(material.subsurfaceColor).toBe(0xffffffff);
+    expect(material.thickness).toBe(0);
+    expect(material.standard.roughness).toBe(1);
+  });
+
+  it('applies overrides', () => {
+    expect(createSubsurfacePbrMaterial({ subsurface: 1 }).subsurface).toBe(1);
+  });
+});
+
+describe('createTransmissionVolumePbrMaterial', () => {
+  it('creates an opaque transmission material with glTF ior and no absorption', () => {
+    const material = createTransmissionVolumePbrMaterial();
+    expect(material.kind).toBe(TransmissionVolumePbrMaterialKind);
+    expect(material.transmission).toBe(0);
+    expect(material.ior).toBe(1.5);
+    expect(material.attenuationColor).toBe(0xffffffff);
+    expect(material.attenuationDistance).toBe(Infinity);
+    expect(material.standard.baseColor).toBe(0xffffffff);
+  });
+
+  it('applies overrides', () => {
+    expect(createTransmissionVolumePbrMaterial({ transmission: 1 }).transmission).toBe(1);
+  });
+});

package/src/pbrMaterials.test.ts

@@ -0,0 +1,91 @@
+import { SpecularGlossinessPbrMaterialKind, StandardPbrMaterialKind } from '@flighthq/types';
+
+import {
+  convertSpecularGlossinessToStandardPbr,
+  createSpecularGlossinessPbrMaterial,
+  createStandardPbrMaterial,
+  createStandardPbrMaterialProperties,
+} from './pbrMaterials';
+
+describe('convertSpecularGlossinessToStandardPbr', () => {
+  it('maps glossiness to roughness as 1 - glossiness', () => {
+    const source = createSpecularGlossinessPbrMaterial({ glossiness: 0.75 });
+    const out = createStandardPbrMaterialProperties();
+    convertSpecularGlossinessToStandardPbr(out, source);
+    expect(out.roughness).toBeCloseTo(0.25, 5);
+  });
+  it('produces metallic=0 for a dielectric (black specular)', () => {
+    const source = createSpecularGlossinessPbrMaterial({ specular: 0x000000ff });
+    const out = createStandardPbrMaterialProperties();
+    convertSpecularGlossinessToStandardPbr(out, source);
+    expect(out.metallic).toBe(0);
+  });
+  it('produces metallic=1 for a full metallic (white specular, white diffuse)', () => {
+    const source = createSpecularGlossinessPbrMaterial({ specular: 0xffffffff, diffuse: 0xffffffff });
+    const out = createStandardPbrMaterialProperties();
+    convertSpecularGlossinessToStandardPbr(out, source);
+    expect(out.metallic).toBeCloseTo(1, 1);
+  });
+  it('forwards emissive, normalMap, and occlusionMap unchanged', () => {
+    const source = createSpecularGlossinessPbrMaterial({ emissive: 0xff000000, emissiveStrength: 2.5 });
+    const out = createStandardPbrMaterialProperties();
+    convertSpecularGlossinessToStandardPbr(out, source);
+    expect(out.emissive).toBe(0xff000000);
+    expect(out.emissiveStrength).toBe(2.5);
+  });
+  it('is alias-safe when out is used as a different object from source', () => {
+    const source = createSpecularGlossinessPbrMaterial({ glossiness: 0.5, diffuse: 0xff0000ff });
+    const out = createStandardPbrMaterialProperties();
+    convertSpecularGlossinessToStandardPbr(out, source);
+    // glossiness=0.5 → roughness=0.5
+    expect(out.roughness).toBeCloseTo(0.5, 5);
+  });
+});
+
+describe('createSpecularGlossinessPbrMaterial', () => {
+  it('creates a white spec-gloss material at full glossiness', () => {
+    const material = createSpecularGlossinessPbrMaterial();
+    expect(material.kind).toBe(SpecularGlossinessPbrMaterialKind);
+    expect(material.diffuse).toBe(0xffffffff);
+    expect(material.specular).toBe(0xffffffff);
+    expect(material.glossiness).toBe(1);
+    expect(material.specularGlossinessMap).toBeNull();
+  });
+
+  it('applies overrides', () => {
+    expect(createSpecularGlossinessPbrMaterial({ glossiness: 0.25 }).glossiness).toBe(0.25);
+  });
+});
+
+describe('createStandardPbrMaterial', () => {
+  it('creates a white, dielectric, fully-rough material', () => {
+    const material = createStandardPbrMaterial();
+    expect(material.kind).toBe(StandardPbrMaterialKind);
+    expect(material.baseColor).toBe(0xffffffff);
+    expect(material.metallic).toBe(0);
+    expect(material.roughness).toBe(1);
+    expect(material.emissive).toBe(0x000000ff);
+    expect(material.baseColorMap).toBeNull();
+  });
+
+  it('applies overrides', () => {
+    const material = createStandardPbrMaterial({ metallic: 1, roughness: 0.2 });
+    expect(material.metallic).toBe(1);
+    expect(material.roughness).toBe(0.2);
+  });
+});
+
+describe('createStandardPbrMaterialProperties', () => {
+  it('creates the property block with no kind or trailer', () => {
+    const properties = createStandardPbrMaterialProperties();
+    expect(properties.baseColor).toBe(0xffffffff);
+    expect(properties.metallic).toBe(0);
+    expect(properties.roughness).toBe(1);
+    expect((properties as { kind?: unknown }).kind).toBeUndefined();
+    expect((properties as { alphaMode?: unknown }).alphaMode).toBeUndefined();
+  });
+
+  it('applies overrides', () => {
+    expect(createStandardPbrMaterialProperties({ roughness: 0.5 }).roughness).toBe(0.5);
+  });
+});

package/src/surfaceMaterial.test.ts

@@ -0,0 +1,69 @@
+import { BlendMode } from '@flighthq/types';
+
+import {
+  createSurfaceMaterial,
+  getMaterialAlphaMode,
+  isMaterialBlended,
+  isMaterialMasked,
+  isMaterialOpaque,
+} from './surfaceMaterial';
+
+const TestSurfaceMaterialKind = 'TestSurfaceMaterial';
+
+describe('createSurfaceMaterial', () => {
+  it('carries the given kind', () => {
+    expect(createSurfaceMaterial(TestSurfaceMaterialKind).kind).toBe(TestSurfaceMaterialKind);
+  });
+
+  it('defaults the shared trailer to an opaque, single-sided surface', () => {
+    const material = createSurfaceMaterial(TestSurfaceMaterialKind);
+    expect(material.alphaMode).toBe('opaque');
+    expect(material.alphaCutoff).toBe(0.5);
+    expect(material.alphaType).toBe('straight');
+    expect(material.blendMode).toBe(BlendMode.Normal);
+    expect(material.doubleSided).toBe(false);
+  });
+});
+
+describe('getMaterialAlphaMode', () => {
+  it('returns the alphaMode of the material', () => {
+    const opaque = createSurfaceMaterial(TestSurfaceMaterialKind);
+    expect(getMaterialAlphaMode(opaque)).toBe('opaque');
+    const blended = createSurfaceMaterial(TestSurfaceMaterialKind);
+    blended.alphaMode = 'blend';
+    expect(getMaterialAlphaMode(blended)).toBe('blend');
+    const masked = createSurfaceMaterial(TestSurfaceMaterialKind);
+    masked.alphaMode = 'mask';
+    expect(getMaterialAlphaMode(masked)).toBe('mask');
+  });
+});
+
+describe('isMaterialBlended', () => {
+  it('returns true only for blend mode', () => {
+    const opaque = createSurfaceMaterial(TestSurfaceMaterialKind);
+    expect(isMaterialBlended(opaque)).toBe(false);
+    const blended = createSurfaceMaterial(TestSurfaceMaterialKind);
+    blended.alphaMode = 'blend';
+    expect(isMaterialBlended(blended)).toBe(true);
+  });
+});
+
+describe('isMaterialMasked', () => {
+  it('returns true only for mask mode', () => {
+    const opaque = createSurfaceMaterial(TestSurfaceMaterialKind);
+    expect(isMaterialMasked(opaque)).toBe(false);
+    const masked = createSurfaceMaterial(TestSurfaceMaterialKind);
+    masked.alphaMode = 'mask';
+    expect(isMaterialMasked(masked)).toBe(true);
+  });
+});
+
+describe('isMaterialOpaque', () => {
+  it('returns true only for opaque mode', () => {
+    const opaque = createSurfaceMaterial(TestSurfaceMaterialKind);
+    expect(isMaterialOpaque(opaque)).toBe(true);
+    const blended = createSurfaceMaterial(TestSurfaceMaterialKind);
+    blended.alphaMode = 'blend';
+    expect(isMaterialOpaque(blended)).toBe(false);
+  });
+});

package/src/unlitMaterials.test.ts

@@ -0,0 +1,127 @@
+import {
+  DepthMaterialKind,
+  EmissiveMaterialKind,
+  MatcapMaterialKind,
+  NormalMaterialKind,
+  ToonMaterialKind,
+  UnlitMaterialKind,
+  VertexColorMaterialKind,
+  WireframeMaterialKind,
+} from '@flighthq/types';
+
+import {
+  createDepthMaterial,
+  createEmissiveMaterial,
+  createMatcapMaterial,
+  createNormalMaterial,
+  createToonMaterial,
+  createUnlitMaterial,
+  createVertexColorMaterial,
+  createWireframeMaterial,
+} from './unlitMaterials';
+
+describe('createDepthMaterial', () => {
+  it('creates a depth material with a unit range', () => {
+    const material = createDepthMaterial();
+    expect(material.kind).toBe(DepthMaterialKind);
+    expect(material.near).toBe(0);
+    expect(material.far).toBe(1);
+  });
+
+  it('applies overrides', () => {
+    expect(createDepthMaterial({ far: 100, near: 0.1 }).far).toBe(100);
+  });
+});
+
+describe('createEmissiveMaterial', () => {
+  it('creates a white emissive material at unit strength', () => {
+    const material = createEmissiveMaterial();
+    expect(material.kind).toBe(EmissiveMaterialKind);
+    expect(material.emissive).toBe(0xffffffff);
+    expect(material.emissiveMap).toBeNull();
+    expect(material.emissiveStrength).toBe(1);
+  });
+
+  it('applies overrides', () => {
+    expect(createEmissiveMaterial({ emissiveStrength: 4 }).emissiveStrength).toBe(4);
+  });
+});
+
+describe('createMatcapMaterial', () => {
+  it('creates a matcap material with a white tint and no capture', () => {
+    const material = createMatcapMaterial();
+    expect(material.kind).toBe(MatcapMaterialKind);
+    expect(material.matcap).toBeNull();
+    expect(material.tint).toBe(0xffffffff);
+  });
+
+  it('applies overrides', () => {
+    expect(createMatcapMaterial({ tint: 0xff0000ff }).tint).toBe(0xff0000ff);
+  });
+});
+
+describe('createNormalMaterial', () => {
+  it('creates a normal material at unit scale with no map', () => {
+    const material = createNormalMaterial();
+    expect(material.kind).toBe(NormalMaterialKind);
+    expect(material.normalMap).toBeNull();
+    expect(material.normalScale).toBe(1);
+  });
+
+  it('applies overrides', () => {
+    expect(createNormalMaterial({ normalScale: 0.5 }).normalScale).toBe(0.5);
+  });
+});
+
+describe('createToonMaterial', () => {
+  it('creates a white toon material with three bands', () => {
+    const material = createToonMaterial();
+    expect(material.kind).toBe(ToonMaterialKind);
+    expect(material.baseColor).toBe(0xffffffff);
+    expect(material.baseColorMap).toBeNull();
+    expect(material.ramp).toBeNull();
+    expect(material.steps).toBe(3);
+  });
+
+  it('applies overrides', () => {
+    expect(createToonMaterial({ steps: 5 }).steps).toBe(5);
+  });
+});
+
+describe('createUnlitMaterial', () => {
+  it('creates a white unlit material with no map', () => {
+    const material = createUnlitMaterial();
+    expect(material.kind).toBe(UnlitMaterialKind);
+    expect(material.baseColor).toBe(0xffffffff);
+    expect(material.baseColorMap).toBeNull();
+  });
+
+  it('applies overrides', () => {
+    expect(createUnlitMaterial({ baseColor: 0x00ff00ff }).baseColor).toBe(0x00ff00ff);
+  });
+});
+
+describe('createVertexColorMaterial', () => {
+  it('creates a vertex-color material with a white tint', () => {
+    const material = createVertexColorMaterial();
+    expect(material.kind).toBe(VertexColorMaterialKind);
+    expect(material.tint).toBe(0xffffffff);
+  });
+
+  it('applies overrides', () => {
+    expect(createVertexColorMaterial({ tint: 0x808080ff }).tint).toBe(0x808080ff);
+  });
+});
+
+describe('createWireframeMaterial', () => {
+  it('creates a white wireframe material one pixel thick', () => {
+    const material = createWireframeMaterial();
+    expect(material.kind).toBe(WireframeMaterialKind);
+    expect(material.color).toBe(0xffffffff);
+    expect(material.thickness).toBe(1);
+  });
+
+  it('applies overrides', () => {
+    expect(createWireframeMaterial({ thickness: 2 }).thickness).toBe(2);
+  });
+});