Document removal of MultiMaterial

[brianchirls]

Description of the problem

I see in 6f52239 and a few related commits that MultiMaterial is being removed (not exactly "deprecated"). There remains some code referencing MultiMaterial throughout the repo, such as ColladaLoader, which is now broken.

I don't see any documentation on this, either in the doc files or in an issue. Can someone please explain how MultiMaterial's functionality is to be replaced? Is there a particular reason for the removal?

Three.js version

• Dev
• r84
• ...

Browser

• All of them
• Chrome
• Firefox
• Internet Explorer

OS

• All of them
• Windows
• Linux
• Android
• IOS

[WestLangley]

The change was proposed in #8924.

With the adopted API, both of these patterns are now acceptable:

var mesh = new THREE.Mesh( geometry, material ); // a single material

var mesh = new THREE.Mesh( geometry, materials ); // an array of materials

[brianchirls]

Thanks @WestLangley.

I'm sure others could still benefit from an update to the docs.

It looks like right now the Mesh just blindly takes whatever you give it, which is going to break a lot of old code and make it a little trickier to inspect Meshes' materials. I quite like the pattern you proposed here.

[mrdoob]

which is going to break a lot of old code and make it a little trickier to inspect Meshes' materials.

How so?

[RemusMar]

It looks like right now the Mesh just blindly takes whatever you give it, which is going to break a lot of old code

Not at all (and it won't break anything).
Finally, the current approach is the right one.
Now you can perform the following task:

if ( object.material.length > 1 ) {
	for (var m = 0; m < object.material.length; m++) {
		object.material[m].color.set( 0xffffff );
	}
} else {
	object.material.color.set( 0xffffff );
}

[mrdoob]

I would use Array.isArray()...

if ( Array.isArray( object.material ) ) {
	for ( var m = 0; m < object.material.length; m ++ ) {
		object.material[ m ].color.set( 0xffffff );
	}
} else {
	object.material.color.set( 0xffffff );
}

[mrdoob]

Okay, serialisation/deserialisation is done ✌️

[mrdoob]

So, from now on... this code:

var geometry = new THREE.BoxBufferGeometry( 1, 1, 1 );
var materials = [
	new THREE.MeshDepthMaterial(),
	new THREE.MeshNormalMaterial(),
	new THREE.MeshBasicMaterial( { wireframe: true } ),
	new THREE.MeshLambertMaterial( { color: 0xff0000 } ),
	new THREE.MeshPhongMaterial( { color: 0x0000ff } ),
	new THREE.MeshStandardMaterial( { color: 0x00ff00 } ),
];
var mesh = new THREE.Mesh( geometry, materials );
mesh.toJSON();

produces this:

{
	"metadata": {
		"version": 4.5,
		"type": "Object",
		"generator": "Object3D.toJSON"
	},
	"geometries": [
		{
			"uuid": "BC2110E2-3EA4-4C37-9041-DE1A49F5C06B",
			"type": "BoxBufferGeometry",
			"width": 1,
			"height": 1,
			"depth": 1
		}
	],
	"materials": [
		{
			"uuid": "81EDCE16-A1EC-40B6-A4F3-D34374C6DF5A",
			"type": "MeshDepthMaterial",
			"depthFunc": 3,
			"depthTest": true,
			"depthWrite": true,
			"skinning": false,
			"morphTargets": false,
			"dithering": false
		},
		{
			"uuid": "8BBB3EE7-B8BD-4441-8CBF-B01A73DE1D9E",
			"type": "MeshNormalMaterial",
			"depthFunc": 3,
			"depthTest": true,
			"depthWrite": true,
			"skinning": false,
			"morphTargets": false,
			"dithering": false
		},
		{
			"uuid": "D3CD2958-6E36-42CE-B4C4-688B670CF8CD",
			"type": "MeshBasicMaterial",
			"color": 16777215,
			"depthFunc": 3,
			"depthTest": true,
			"depthWrite": true,
			"wireframe": true,
			"skinning": false,
			"morphTargets": false,
			"dithering": false
		},
		{
			"uuid": "22156F77-0963-4C68-99A7-BDE887313F2A",
			"type": "MeshLambertMaterial",
			"color": 16711680,
			"emissive": 0,
			"depthFunc": 3,
			"depthTest": true,
			"depthWrite": true,
			"skinning": false,
			"morphTargets": false,
			"dithering": false
		},
		{
			"uuid": "49C93E84-FD7F-49F4-AA55-9769194E25E8",
			"type": "MeshPhongMaterial",
			"color": 255,
			"emissive": 0,
			"specular": 1118481,
			"shininess": 30,
			"depthFunc": 3,
			"depthTest": true,
			"depthWrite": true,
			"skinning": false,
			"morphTargets": false,
			"dithering": false
		},
		{
			"uuid": "F8B0E57E-B25C-4A16-B917-4EE615B2B6D4",
			"type": "MeshStandardMaterial",
			"color": 65280,
			"roughness": 0.5,
			"metalness": 0.5,
			"emissive": 0,
			"depthFunc": 3,
			"depthTest": true,
			"depthWrite": true,
			"skinning": false,
			"morphTargets": false,
			"dithering": false
		}
	],
	"object": {
		"uuid": "6E9A5918-B4C7-4D25-928D-4C283C8CE387",
		"type": "Mesh",
		"matrix": [1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1],
		"geometry": "BC2110E2-3EA4-4C37-9041-DE1A49F5C06B",
		"material": [
			"81EDCE16-A1EC-40B6-A4F3-D34374C6DF5A",
			"8BBB3EE7-B8BD-4441-8CBF-B01A73DE1D9E",
			"D3CD2958-6E36-42CE-B4C4-688B670CF8CD",
			"22156F77-0963-4C68-99A7-BDE887313F2A",
			"49C93E84-FD7F-49F4-AA55-9769194E25E8",
			"F8B0E57E-B25C-4A16-B917-4EE615B2B6D4"
		]
	}
}

And THREE.ObjectLoader loads that correctly.

[mrdoob]

The editor now also has minimal support (import, export but not edit).