MultiMaterial : Material

multimaterial - superclass: material; super-superclass:MAXWrapper - classID: #(512, 0) 

Constructor

multimaterial [numsubs:<integer>]
multiSubMaterial [numsubs:<integer>]   

Properties

<multimaterial>.numsubs 

Sets the number of sub-materials in the MultiMaterial.

When getting this value, the result will be the number of sub-anims in the MultiMaterial.

Please see the Historical Notes at the end of this page for important details on how the behaviour of this property has changed between 3ds Max versions.

<multimaterial>.materialList ArrayParameter default: #(Standard, Standard, ... Standard, Standard) 

Stores the Material for each sub-material.

<multimaterial>.mapEnabled ArrayParameter default: #(true, true, ... true, true) 

Stores whether the sub-material is enabled.

<multimaterial>.names ArrayParameter default: #("", "", ... "", "") 

Stores the sub-material slot name (not the sub-material name).

<multimaterial>.materialIDList ArrayParameter default: #(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) -- int array; Index 

Stores the sub-material ID’s.

<multimaterial>.material1 Standardmaterial default: Standard -- alias for materialList[0]; SubAnim 

Stores the material.

Each of the arrays contains as many elements as there are sub-materials.

The materialList array stores the Material for each sub-material.

The mapEnabled array stores whether that sub-material is enabled.

The names array stores the sub-material slot name (not the sub-material name).

The materialIDList stores the Material ID corresponding to the sub-material.

If the numsubs named parameter is not specified, the default numsubs value is 10.

The number of sub-materials can be changed after material creation by changing the numsubs property value.

The number of sub-materials can also be changed by setting the count property for the materialList,mapEnabled , or names property to the desired number.

material1 is an alias for materialList\[1\] .

In versions prior to 3ds Max 4, MultiMaterials had sub-materials arranged in a table, so MAXScript also allowed access to these sub-materials using the array indexing accessor:

FOR EXAMPLE

mm = multimaterial numsubs:3
mm[1] = $foo.material
$baz.material = mm[2]

See the notes below regarding indexed access in newer versions of 3ds Max.

HISTORICALNOTES REGARDING .NUMSUBS:

The .numsubs property is normally a read-only property that returns the number of immediate subAnims in any MAXWrapper as explained in the topic Indexed Access to Animatable Properties in3ds Max Objects.

Originally, in 3ds Max prior to version 4, the value returned by the .numsubs property in the MultiMaterial was equivalent to the number of sub-materials in the MultiMaterial because there were always as many sub-materials in the MultiMaterial as there were Material IDs to be assigned. In addition, the .numsubs property can be both get and set in a MultiMaterial.

After the introduction of the .materialIDList property that specifies the correspondence between the sub-materials and the Material IDs, it became possible to have sub-materials corresponding to much higher Material IDs than the total number of sub-materials. In this case, the number of sub-anims in the MultiMaterial will be set internally to reflect the highest ID, with any sub-anims without corresponding Material IDs left undefined.

FOR EXAMPLE

Creating a default MultiMaterial with 10 sub-materials and accessing the .count of the MaterialIDList or .materialList and the .numsubs property always returns 10:

theMat = multiMaterial()
--> #Multi/Sub-Object:Multimaterial(Standard:Material #25, Standard:Material #26, Standard:Material #27, Standard:Material #28, Standard:Material #29, Standard:Material #30, Standard:Material #31, Standard:Material #32, Standard:Material #33, Standard:Material #34)
theMat.materialList.count
--> 10
theMat.numsubs
--> 10

But, assigning Material ID 20 to the 10 th material and looking at the same values shows a different picture:

theMat.materialIDList[10]=20
--> 20
theMat.materialIDList
--> #(1, 2, 3, 4, 5, 6, 7, 8, 9, 20)
theMat.materialList.count--still 10 sub-materials
--> 10
theMat.numsubs--but the number of sub-anims is 20!
--> 20
--Let's print the sub-anims to get a better idea:
for i = 1 to theMat.numsubs do format "%: %\n" i theMat[i]
--> 1: Material #25:Standard
--> 2: Material #26:Standard
--> 3: Material #27:Standard
--> 4: Material #28:Standard
--> 5: Material #29:Standard
--> 6: Material #30:Standard
--> 7: Material #31:Standard
--> 8: Material #32:Standard
--> 9: Material #33:Standard
--> 10: undefined
--> 11: undefined
--> 12: undefined
--> 13: undefined
--> 14: undefined
--> 15: undefined
--> 16: undefined
--> 17: undefined
--> 18: undefined
--> 19: undefined
--> 20: Material #34:Standard
--> OK

From this example it is obvious that the sub-material 10 corresponding to Material ID 20 was stored internally in the sub-anim track 20, leaving sub-anims 10 to 19 undefined.

Thus, it is a good idea to use the .materialList property to iterate through sub-materials instead of using the indexed access to sub-anims.

See also How do I Sort a MultiMaterial By Material ID? in the FAQ Chapter for more examples of working with MultiMaterials.