Skip to content

3D engine that AI agents drive

Accept MeshLambertMaterial and MeshPhongMaterial in the three.js addon (#986)

Nguyen Xuan Anaaf774284b57
diff --git a/changes/986-lambert-phong.md b/changes/986-lambert-phong.md
new file mode 100644
index 00000000..bb8b078d
--- /dev/null
+++ b/changes/986-lambert-phong.md
@@ -0,0 +1 @@
+- The three.js addon accepts `MeshLambertMaterial` and `MeshPhongMaterial` and maps them to matte Crucible materials (#986)
diff --git a/docs/learn/if-you-know-three-js.md b/docs/learn/if-you-know-three-js.md
index d6e56cd2..3b31aa30 100644
--- a/docs/learn/if-you-know-three-js.md
+++ b/docs/learn/if-you-know-three-js.md
@@ -35,6 +35,8 @@ If you would rather write three.js-shaped code, the optional addon `packages/thr
| three.js | Crucible |
| --- | --- |
| `new THREE.MeshStandardMaterial({ color, metalness, roughness })` | `material: { color, metallic, roughness }`. `color` is three linear numbers from 0 to 1, not a hex number. |
+| `new THREE.MeshLambertMaterial({ color })` | `material: { color, metallic: 0, roughness: 1 }`. |
+| `new THREE.MeshPhongMaterial({ color, shininess })` | `material: { color, metallic: 0, roughness }`. The addon turns `shininess` into `roughness` (the square root of 2 divided by shininess plus 2) and ignores `specular`. |
| `emissive` and `emissiveIntensity` | `material.emission` and `material.emissiveColor`. |
| `map`, `normalMap` | `material.map` and `material.normalMap`, each `{ image, colorSpace }`. |
| `transparent` and `opacity` | `material.alphaMode` set to `'blend'`, and `material.opacity`. |
@@ -118,7 +120,7 @@ import { createThreeCompat } from '@codepawlhq/crucible-three-compat';
const THREE = createThreeCompat({ ...core, loadGltf });
```
-It accepts `Scene`, `Group`, `Mesh`, the box, plane, sphere, cylinder and torus geometries, `MeshStandardMaterial`, `MeshPhysicalMaterial`, both cameras, the light classes, `GLTFLoader`, `OrbitControls` and `WebGLRenderer` with `setAnimationLoop`. For any other three.js name it throws an error that names the Crucible call to use. For example, `THREE.MeshBasicMaterial` tells you to use `MeshStandardMaterial` with `emissive`, which is `material.emission` in Crucible.
+It accepts `Scene`, `Group`, `Mesh`, the box, plane, sphere, cylinder and torus geometries, `MeshStandardMaterial`, `MeshPhysicalMaterial`, `MeshLambertMaterial`, `MeshPhongMaterial`, both cameras, the light classes, `GLTFLoader`, `OrbitControls` and `WebGLRenderer` with `setAnimationLoop`. For any other three.js name it throws an error that names the Crucible call to use. For example, `THREE.MeshBasicMaterial` tells you to use `MeshStandardMaterial` with `emissive`, which is `material.emission` in Crucible.
To move a scene you already have, the [three.js bridge](../three-bridge.md) imports a three.js object tree as Crucible parts and builds three.js meshes from parts.
diff --git a/packages/three-compat/index.mjs b/packages/three-compat/index.mjs
index 91dff3fc..8c2f4c6b 100644
--- a/packages/three-compat/index.mjs
+++ b/packages/three-compat/index.mjs
@@ -16,8 +16,6 @@ const GUIDE = 'docs/learn/if-you-know-three-js.md';
const UNSUPPORTED = {
MeshBasicMaterial: 'Use MeshStandardMaterial with emissive and emissiveIntensity (Crucible: material { color, emission }).',
- MeshLambertMaterial: 'Use MeshStandardMaterial (Crucible: material { color, metallic: 0, roughness }).',
- MeshPhongMaterial: 'Use MeshStandardMaterial (Crucible: material { color, metallic, roughness }).',
MeshNormalMaterial: 'Use MeshStandardMaterial (Crucible: material { color, metallic, roughness }).',
ShaderMaterial: 'Crucible has no custom shaders. Use the material fields of materials-and-color (Crucible: part.material).',
RawShaderMaterial: 'Crucible has no custom shaders. Use the material fields of materials-and-color (Crucible: part.material).',
@@ -394,7 +392,7 @@ export function createThreeCompat(core) {
class MeshStandardMaterial {
constructor(parameters = {}) {
- const rejected = UNSUPPORTED_OPTIONS[new.target.name === 'MeshPhysicalMaterial' ? 'MeshStandardMaterial' : new.target.name] ?? {};
+ const rejected = UNSUPPORTED_OPTIONS.MeshStandardMaterial;
for (const option of Object.keys(parameters)) {
if (rejected[option]) throw unsupported(`${new.target.name} option "${option}"`, rejected[option]);
}
@@ -459,6 +457,23 @@ export function createThreeCompat(core) {
}
}
+ // MeshLambertMaterial: a matte surface, so Crucible roughness 1 and no metal.
+ class MeshLambertMaterial extends MeshStandardMaterial {
+ constructor(parameters = {}) {
+ super({ ...parameters, metalness: 0, roughness: 1 });
+ }
+ }
+
+ // MeshPhongMaterial: shininess becomes roughness with the usual Blinn-Phong to GGX fit, roughness = sqrt(2 / (shininess + 2)).
+ // The specular color has no Crucible field and is ignored.
+ class MeshPhongMaterial extends MeshStandardMaterial {
+ constructor(parameters = {}) {
+ const shininess = parameters.shininess ?? 30;
+ super({ ...parameters, metalness: 0, roughness: Math.sqrt(2 / (shininess + 2)) });
+ this.shininess = shininess;
+ }
+ }
+
class Mesh extends Object3D {
constructor(geometry, material = new MeshStandardMaterial()) {
super();
@@ -466,7 +481,7 @@ export function createThreeCompat(core) {
throw new CompatError('Mesh needs BoxGeometry, SphereGeometry, CylinderGeometry, TorusGeometry or PlaneGeometry (Crucible: box(), sphere(), cylinder(), torus()).');
}
if (!(material instanceof MeshStandardMaterial)) {
- throw new CompatError('Mesh needs MeshStandardMaterial or MeshPhysicalMaterial (Crucible: a material { color, metallic, roughness }).');
+ throw new CompatError('Mesh needs MeshStandardMaterial, MeshPhysicalMaterial, MeshLambertMaterial or MeshPhongMaterial (Crucible: a material { color, metallic, roughness }).');
}
this.geometry = geometry;
this.material = material;
@@ -834,7 +849,7 @@ export function createThreeCompat(core) {
const exported = {
Color, Vector2, Vector3, Euler, Object3D, Group, Scene, Mesh, Clock,
BoxGeometry, PlaneGeometry, SphereGeometry, CylinderGeometry, TorusGeometry,
- Texture, CanvasTexture, MeshStandardMaterial, MeshPhysicalMaterial,
+ Texture, CanvasTexture, MeshStandardMaterial, MeshPhysicalMaterial, MeshLambertMaterial, MeshPhongMaterial,
PerspectiveCamera, OrthographicCamera,
AmbientLight, HemisphereLight, DirectionalLight, PointLight, SpotLight, RectAreaLight,
WebGLRenderer, OrbitControls, GLTFLoader,
diff --git a/tests/three-compat.test.js b/tests/three-compat.test.js
index 84e0db8b..6f3f96e1 100644
--- a/tests/three-compat.test.js
+++ b/tests/three-compat.test.js
@@ -147,6 +147,21 @@ test('OrbitControls moves the camera around its target', () => {
assert.ok(Math.abs(camera.position.z) < 1e-6);
});
+test('MeshLambertMaterial and MeshPhongMaterial build matte Crucible materials', () => {
+ const lambert = new THREE.MeshLambertMaterial({ color: 0xff0000, metalness: 1, roughness: 0 }).toMaterial();
+ assert.equal(lambert.metallic, 0);
+ assert.equal(lambert.roughness, 1);
+ assert.deepEqual(lambert.color, new THREE.Color(0xff0000).toArray());
+ const defaultPhong = new THREE.MeshPhongMaterial({ color: 0x00ff00 }).toMaterial();
+ assert.equal(defaultPhong.metallic, 0);
+ assert.ok(Math.abs(defaultPhong.roughness - Math.sqrt(2 / 32)) < 1e-9);
+ const shiny = new THREE.MeshPhongMaterial({ shininess: 198, specular: 0xffffff }).toMaterial();
+ assert.ok(Math.abs(shiny.roughness - 0.1) < 1e-9);
+ const mesh = new THREE.Mesh(new THREE.BoxGeometry(), new THREE.MeshPhongMaterial());
+ assert.ok(mesh.material instanceof THREE.MeshStandardMaterial);
+ assert.ok(!unsupportedNames.includes('MeshLambertMaterial') && !unsupportedNames.includes('MeshPhongMaterial'));
+});
+
test('unsupported three.js names throw an error that names the Crucible replacement', () => {
const cases = [
['MeshBasicMaterial', /MeshStandardMaterial.*emission/],