MAXScript Language Reference > Collections > Collection Types >

# 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 strictly speaking 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. Please see the note in the beginning of this topic.

    materialLibrary { <material> }

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

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 the loads succeeds, false if it fails.

    saveMaterialLibrary <filename_string>

Saves the current material library into the named file. Returns true if the save succeeds, false if it fails.

    fileOpenMatLib()

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

NoteIf 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 at 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 through all the currently configured bitmap paths. Returns MAXMaterialLibrary value if the loading succeeded, undefined if it failed.

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 the save succeeded, false if it failed.

Available in 3ds Max 9 and higher.

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 at materials in them by name:
    a = loadTempMaterialLibrary "mrArch_DesignTemplates.mat"
    #materialLibrary()
    a[1]
    brushed metal:Arch___Design__mi
    saveTempMaterialLibrary a "$matlibs/test.mat"
    true