3ds Max File Loading and Saving

The following methods are used to load, save, merge, import, and export 3ds Max scenes.

<boolean>loadMaxFile <filename_string> [useFileUnits:<bool>] [quiet:<bool>]

Returns true if the file was found and loaded successfully.

If useFileUnits:false, the file objects will be rescaled to the current System's unit scale. If true, the System's unit scale will be changed to the File's unit scale. This option will apply regardless of the Respect System Units in Files option setting in the System Units Setup dialog. Loading a file with useFileUnits:true will not change the system units setting in the 3dsmax.ini file. useFileUnits defaults to false for 3ds Max, true for Autodesk VIZ.

For details on the quiet: option, please see Quiet Mode

<boolean>mergeMAXFile <filename_string> [<name_array>] [#prompt] \

[ [ #select ] #noRedraw ] \

[ #deleteOldDups | #mergeDups | #skipDups | #promptDups ] \

[ #promptMtlDups | #useMergedMtlDups | #useSceneMtlDups | #renameMtlDups ]\

[ #promptReparent | #alwaysReparent | #neverReparent ] \

[ quiet:<bool> ] \
missingExtFilesAction: <actions> missingExtFilesList: <&variable> \
missingXRefsAction: <actions> missingXRefsList: <&variable>

All arguments are optional except the initial file name. The flag arguments can be specified in any order. The arguments details are as follows:

<name_array>

An optional array of names or strings identifying the objects in the source scene file to be merged; all objects are merged if not specified.

#prompt

If specified causes the standard merge dialog to be opened.

#select

If specified causes the newly merged objects to be selected when merged.

#noRedraw

If specified causes the screen redraw to be delayed in case you want to call mergeMAXFile several times and delay the redraw until after the last file merge.

#deleteOldDups

Deletes existing scene objects with the same names as incoming objects, equivalent to a replace.

#mergeDups

Ignore name conflicts, merge anyway resulting in possibly duplicated names.

#skipDups

Don't merge objects with duplicated names.

#promptDups

Throw up the duplicates resolution dialog for the user to choose.

#promptMtlDups

Default, prompt the user when duplicated materials are found.

#useMergedMtlDups

Merge using the incoming materials.

#useSceneMtlDups

Merge using the scene materials.

#renameMtlDups

Merge and rename duplicated incoming materials.

#promptReparent

Default, prompt the user.

#alwaysReparent

Don't ask the user, always reparent.

#neverReparent

Don't ask the user, never reparent.

For details on the quiet: option, please see Quiet Mode

mergeMAXFile returns true if the file was found and loaded successfully. Returns false when the argument is a file with .DRF extension.

If you don't specify a full path name, the file is looked for in the 3ds Max scene directory, then in the 3ds Max executable directory, and then in the PATH environment directories.

getMAXSaveFileName filename: <seed_filename_string>

Displays standard 3ds Max file save dialog, returns file name or value 'undefined' if canceled.

getMAXOpenFileName filename: <seed_filename_string> dir:<seed_directory_string>

Displays standard 3ds Max file open dialog, returns file name or value 'undefined' if canceled.

getMAXFileObjectNames <max_filename_string> [ quiet:<bool> ]

Returns an array of strings, one for each of the names of the objects in the given 3ds Max file. This provides a way to get a preview list of the objects in another scene file (by name) to set up user selection of the objects to be merged under script control using the mergeMAXFile() function,

For Example:

p=[1000,1000,1000]

for i = 1 to 5 do box pos:(random p -p) -- create some boxes

savemaxfile "mergetest.max" -- save to file

for obj in objects do obj.name = "_"+obj.name -- rename the boxes

objects.pos += [0,-1000,0] -- move them off to the side

fobj_names = getmaxfileobjectnames "mergetest.max" -- get the object names from the file

deleteitem fobj_names 3 -- delete the third name from the array

mergemaxfile "mergetest.max" fobj_names #select -- merge in the objects and select them

selection.count -- should be 4

objects.count -- should be 9

getMAXFileObjectNames returns an empty array when the argument is a file with .DRF extension.

For details on the quiet: option, please see Quiet Mode

getMAXFileObjectNames in 3ds Max 7 and higher returns an array of string values, rather than the array of name values in previous 3ds Max versions. The object names used by mergeMaxFile are case sensitive, and name values are not guaranteed to maintain the case of the string they wrap.

 

<bool>saveMaxFile <filename_string> [clearNeedSaveFlag:<bool>] [useNewFile:<bool>] [quiet:<bool>]

Saves the scene to the current 3ds Max scene directory if there is no explicit directory path on the supplied file name. If no filename extension is specified, ".max" is automatically appended to the filename.

See WARNING at the end of this page regarding overwriting existing files!

The optional keywords are true by default to match the existing behavior prior to 3ds Max 6.

If clearNeedSaveFlag is set to false, the file is saved, but the need save flag will not be cleared and 3ds Max will still consider the scene as changed and requiring saving.

If useNewFile is false, the saved file is not set as the current scene file and the file is not put in the Most Recently Used list. This lets you save a backup file of the scene to a different name without the name becoming the current one or appearing on the list of recent files.

For details on the quiet: option which was added to this method in 3ds Max 8, please see Quiet Mode

The method will return true on success or false if the saving failed (for example if attempting to overwrite an existing read-only file) in 3ds Max 8 and higher.

 

holdMaxFile()

Equivalent to the 3ds Max Edit > Hold operation.

 

fetchMaxFile [quiet:<boolean>]

Equivalent to the 3ds Max Edit > Fetch operation. For details on the quiet: option, please see Quiet Mode

 

<bool>isMaxFile <filename_string>

Returns true if the specified file is a MAX file. This method tests the internal structure of the file to see if it is consistent with a MAX file. Returns false if the file is not a MAX file or if the specified file does not exist.

Examples:

isMaxFile "$scenes/ca_test1.max" --returns true if file exists

isMaxFile "$max/autoback/maxhold.mx" --returns true if file exists

isMaxFile "$matlibs/Nature.mat" --returns true if file exists

isMaxFile (maxFilePath + maxFileName) --returns true unless the scene is Untitled

 

 

importFile <filename_string> [ #noPrompt ] [ using:<maxclass> ]

Lets you import files using any of the import plug-ins that are available. The kind of file imported is determined by the file name suffix such as DFX for .dxf, 3DS DOS for .3ds, etc.

The #noPrompt flag prevents any configuration or control dialogs from being displayed in which case the default configuration is used.

If the optional keyword argument using: is supplied, the respective I/O class will be used to perform the import. This can be useful when multiple plug-ins support the same file format extension. Available in 3ds Max 8 and higher.

To see all available importer plug-in classes, you can access the .classes property of the importerPlugin value - it returns an array of all installed importer plug-ins:

For example

print importerPlugin.classes

3D_Studio

3D_Studio_Shape

Adobe_Illustrator_Shape

AutoCADImport

FBXIMP

STL_Import

FileLinkAsDwgImporter

mental_ray_Import

IGES_Import

Wavefront_Object

VrmlImp

ImportTRC

Lightscape_Importer

XMLImp2

ImportHTR

InventorImport

LandXML___DEM_Model_Import

Wavefront_Material

 

exportFile <filename_string> [ #noPrompt ] [ selectedOnly:<boolean> ] [ using:<maxclass> ]

Lets you export files using any of the export plug-ins that are available. The kind of file exported is determined by the file name suffix such as DFX for .dxf, 3DS DOS for .3ds, etc.

The #noPrompt flag prevents any configuration or control dialogs from being displayed in which case the default configuration is used.

If the selectedOnly keyword parameter is set to true, only selected nodes are exported. Defaults to false.

If the optional keyword argument using: is supplied, the respective I/O class will be used to perform the export. This can be useful when multiple plug-ins support the same file format extension. Available in 3ds Max 8 and higher.

To get an array of all available exporter plug-in classes, you can access the .classes property of the exporterPlugin value:

For example

theClasses = exporterPlugin.classes

exportFile (GetDir #scene + "/exportTest" ) using:theClasses[1]

In the example above, the export will use the first plug-in found in the array, which is by default the 3D_StudioExporterPlugin.

 

<bool>saveNodes <node_collection> <filename_string> [quiet:<bool>]

Creates a new .max scene file with the given name and stores the node collection to it. The <node_collection> argument can be a single node, an array of nodes you gathered, a wild-card path name, one of the built-in objects sets such as selection or lights, or a <node>.children array. If no filename extension is specified, ".max" is automatically appended to the filename.

For details on the quiet: option which was added to this method in 3ds Max 8, please see Quiet Mode

The method will return true on success or false if the saving failed (for example if attempting to overwrite an existing read-only file) in 3ds Max 8 and higher.

See WARNING below regarding overwriting existing files!

 

checkForSave()

If the scene has been modified since the last file save (if any), calling this function displays the message box prompting the user that the scene has been modified and requests to save. Function returns false if the user cancels out of the save, true otherwise. See also Exiting and Resetting 3ds Max

WARNING!!! saveNodes and saveMaxFile will overwrite existing files with the same name without warning!

 

For example

b = box()

saveNodes b "foo.max"

saveNodes b "foo.max"

saveMaxFile "foo.max"

You should always use doesFileExist() to make sure the target file does not exist and prompt if it does. Here are two examples of using doesFileExist() for these cases:

Script:

b = box()

-- if filename exists, ask user if ok to overwrite

-- function returns true if file was saved, false otherwise

 

fn maybe_saveNodes nodeArray filename =

(

if getFilenamePath filename == "" do

filename = getdir #scene + "\\" + filename

if (not (doesfileexist filename)) or

querybox ("filename: "+filename + "\nexists. Overwrite?") then

(

saveNodes nodeArray filename

true

)

else

false

)

 

Script:

fn maybe_saveMaxFile filename =

(

if getFilenamePath filename == "" do

filename = getdir #scene + "\\" + filename

if (not (doesfileexist filename)) or

querybox ("filename: "+filename + "\nexists. Overwrite?") then

(

saveMaxFile filename

true

)

else

false

)

 

maybe_saveNodes b "foo.max"

maybe_saveNodes b "foo.max"

maybe_saveMaxFile "foo.max"

See also

External File Methods

File Name Parsing

Standard Open and Save File Dialogs

Exiting and Resetting 3ds Max