MaterialLibrary Values

Value > Collections > Collection Types > MaterialLibrary Values

Values and Collections - Quick Navigation

A MaterialLibrary contains a table of materials as an array.

The 3ds Max system global variables currentMaterialLibrary and sceneMaterials contain MaterialLibrary instances.

System global variable meditMaterials is not a MaterialLibrary value, rather it is a virtual array of the materials in the Material Editor sample slots.

In most cases, meditMaterials can be considered a MaterialLibrary value with the exception that you can assign a material or textureMap value to a meditMaterials element.

MaterialLibrary values are mappable.

Constructors

currentMaterialLibrary

A system global containing the current material library.

sceneMaterials

A system global containing all materials in the scene.

meditMaterials

A system global containing the 24 sample slot materials in the Material Editor.

materialLibrary { <material> }

Creates a temporary material library. You can add materials to this library with the append function, and save it to disk and load it from disk using the saveTempMaterialLibrary and loadTempMaterialLibrary functions documented farther in this topic.

Properties

<mat_lib>.count : Integer, read-only

Returns the number of materials in the library.

Operators

<mat_lib>[ <integer> | <name> | <string> ]

Retrieves a material from the material library. Material libraries can be indexed just like arrays with an integer index, or by using the material name as a Name or String value.

<mat_lib>[ <integer> | <name> | <string> ] = ( <material> | <textureMap> )

Assigns the specified material or textureMap to the material library.

Material libraries can be indexed just like arrays with an integer index, or by using the material name as a Name or String value.

If the material library is indexed by an index value, and the index value is larger than the size of the material library, a runtime error is generated.

If the material library is indexed by a material name, and the material name is not already present in the material library, the material or textureMap is appended to the material library.

meditMaterials[<slot_index_integer>]

Returns the material or textureMap in the indexed material editor slot.

Valid <slot_index_integer> values are 1 through 24.

meditMaterials[<slot_index_integer>] = ( <material> | <textureMap> )

Assigns the specified material or textureMap to the indexed material editor slot.

Valid <slot_index_integer> values are 1 through 24.

FOR EXAMPLE:

meditMaterials[3]= standard()
--sets the third slot of the Material Editor
--to a new standard material.

Methods

append <mat_lib> <material>

Append the specified material to the material library. This method is not applicable to the meditMaterials material library.

deleteItem <mat_lib> ( <integer> | <name> | <string> )

Delete the specified material from the material library. The material can be specified as the indexed material in the material library, as a String or as a Name. This method is not applicable to the meditMaterials material library.

findItem <mat_lib> <material>

Returns the index of the material in the material library or zero if the material is not in the material library.

Associated Methods

getMeditMaterial <slot_index_integer>

Returns the top level material or textureMap in the specified material editor slot. Valid <slot_index_integer> values are 1 through 24.

FOR EXAMPLE:

theMat = getMeditMaterial 3
--gets the material from the third slot of the Material Editor.

setMeditMaterial <slot_index> ( <material> | <textureMap> )

Complements the getMeditMaterial function allowing you to place a material or textureMap into the numbered material editor slot.

loadDefaultMatLib()

Loads the default 3ds Max material library file.

loadMaterialLibrary <filename_string>

Loads the named 3ds Max material library file, which becomes the current material library. If the file name does not have a fully specified directory path, the function searches through all the currently configured bitmap paths. Returns true if loading is successful, false if it fails.

saveMaterialLibrary <filename_string>

Saves the current material library into the named file. Returns true if saving is successful, false if it fails.

fileOpenMatLib()

This method displays the File Open dialog and allows the user to select a material library to load.

NOTE:If the Material/Map Browser is open when fileOpenMatLib() is called, the Material/Map Browser display is not updated.

fileSaveAsMatLib()

Displays the standard Save File As dialog to allow the user to save the current material library.

fileSaveMatLib [quiet:<bool>]

If the current material library has been saved previously (has been named) this method saves the material library to the same file. Otherwise, it displays the standard Save File As dialog to allow the user to save the current material library.

For details on the quiet: option available in 3ds Max 8 and higher, please see Quiet Mode.

getMatLibFileName()

Returns the current material library file name as a String value.

EXAMPLES:

You can use the standard array indexing accessors to get and set materials in the library. MaterialLibraries also allow you to use name and string literals as indexes to get materials in them by name:

$foo.material = currentMaterialLibrary["Rough Gold"]

for m in sceneMaterials do print m.name

append currentMaterialLibrary $baz.material

<MAXMaterialLibrary>loadTempMaterialLibrary <mtllib_file_name>

Loads the named 3ds Max material library file. Unlike loadMaterialLibrary() , the material library does not become the current material library. If the file name does not have a fully specified directory path, the function searches the material library path and all the currently configured bitmap paths. Returns MAXMaterialLibrary value if loading is successful, undefined if it fails.

Available in 3ds Max 9 and higher.

<boolean>saveTempMaterialLibrary <MAXMaterialLibrary> <mtllib_file_name>

Saves the specified MAXMaterialLibrary value into the named file. Returns true if saving is successful, false if it fails.

Available in 3ds Max 9 and higher.

EXAMPLES:

a = loadTempMaterialLibrary "mrArch_DesignTemplates.mat"
--> #materialLibrary()
a[1]
--> brushed metal:Arch___Design__mi
saveTempMaterialLibrary a "$matlibs/test.mat"
--> true

<void> UpdateSceneMaterialLib()

Forces an update to the Scene Material Library (the sceneMaterials global). The Scene Material library is not guaranteed to be accurate after some scene operations. For example, if you delete a node, the material for that node may still appear in the Scene Material library.