3ds Max File Loading and Saving

The following System Globals and Methods are used to access the file name and path and load, save, merge, import, and export 3ds Max scenes.

• Scene File Path and Name
• Loading MAX Files
  • Scene File Path Resolution
• Merging MAX Files
• 3ds Max Load and Save Dialogs
• MAX File Object Names
• Save MAX File
• Set Scene File Name
• Archive MAX File
• Hold and Fetch
• Checking For MAX File
• Importing Files
• Exporting Files
• Saving Nodes
• Check For Save

System Globals:

Scene File Path and Name

maxFileName

Contains a String value that defines the file name for the currently open scene.

This variable is read-only.

It will be set automatically when the scene is loaded or saved using the loadMaxFile() and saveMaxFile() methods described below.

See also the How do I get the file name of the current scene? FAQ entry.

maxFilePath

Contains a String value that defines the directory path for the currently open scene.

This variable is read-only.

It will be set automatically when the scene is loaded or saved using the loadMaxFile() and saveMaxFile() methods described below.

See also the How do I get the file name of the current scene? FAQ entry.

Methods:

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

Loading MAX Files

<boolean>loadMaxFile <filename_string> [useFileUnits:<boolean>] [quiet:<boolean>] [allowPrompts:<boolean>]
    [missingExtFilesAction: (#logmsg|#logToFile|#abort|<int>)] [missingExtFilesList:<&var array of strings>]
    [missingDLLsAction: (#logmsg|#logToFile|#abort|<int>)] [missingDLLsList:<&var array of strings>]
    [missingXRefsAction:(#logmsg|#logToFile|#abort|<int>)] [missingXRefsList:<&var array of strings>]
    [skipXRefs:<boolean>]

Returns true if the file was found and loaded successfully, false otherwise.

The useFileUnits parameter specifies whether to adopt the file's unit scale (if true) or the current System's unit scale (if false, the default). 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.

For details on the quiet: and missing* parameters, see Quiet Mode.

The allowPrompts parameter specifies whether to allow dialogs to appear during the file loading process; the default is false.

The optional skipXRefs parameter allows you to disable scene and object XRefs during scene load to speed up file loading. You can load XRefs later by selecting the reference and updating it.

Scene File Path Resolution

3ds Max searches for the file specified by filename_string in the following places:

• The 3ds Max install directory
• The current .mzp file, If the script is running in zip-file script package, and the file path is relative
• The current working directory (which you can get or set using sysinfo.currentdir)
• The Windows directory, and the system directories (system and system32)
• The directories in the PATH environment variable.

Merging MAX Files

<boolean>mergeMAXFile <filename_string> [<name_array>] [#prompt] \
[ [ #select ] #noRedraw ] \
[ #deleteOldDups | #mergeDups | #skipDups | #promptDups | #autoRenameDups ] \
[ #promptMtlDups | #useMergedMtlDups | #useSceneMtlDups | #renameMtlDups ]\
[ #promptReparent | #alwaysReparent | #neverReparent | #mergeChildren ] \
[ quiet:<boolean> ] \
[ missingExtFilesAction: <actions> ] [ missingExtFilesList: <&variable> ] \
[ missingDLLsAction: <actions>] [ missingDLLsList: <&variable>]
[ missingXRefsAction: <actions> ] [ missingXRefsList: <&variable> ] \
[ mergedNodes: <&variable> | includeFullGroup: <boolean> ] \
[ mergeByHandles: <boolean> ]

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

The arguments details are as follows:

<filename_string>

The scene file to merge. For information about where 3ds Max looks for the specified <filename_string>, see Scene File Path Resolution, above.

<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.

#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.

#AutoRenameDups

Auto-renames the incoming objects that have names that already exist in the current scene. No dialog will pop up. Available in 3ds Max 2011 and higher.

#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: and missing* parameters, 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.

#mergeChildren

NEW in 3ds Max 2024: Automatically merge children.

mergedNodes <&variable>

On a successful merge, the specified variable will contain an array of merged nodes.

includeFullGroup: <boolean>

When true, if a an imported node is part of a group, all the nodes in that group are also imported. The default is false.

Available in 3ds Max 2020 and higher.

mergeByHandles: <boolean>

NEW in 3ds Max 2024: When true, the <name_array> is a list of node handle IDs instead of a list of names.

<nodes array>getLastMergedNodes()

Available in 3ds Max 2017 and higher: Returns an array of the nodes merged in the last merge operation.

Returns an empty array #() if no merge operations have been performed in the current scene.

EXAMPLE

resetMaxFile #noPrompt --reset the scene
--> OK

getLastMergedNodes() --get the last merged nodes - returns an empty array, because nothing has been merged yet
--> #()

t = teapot() --create a teapot
--> $Teapot:Teapot001 @ [0.000000,0.000000,0.000000]

s = sphere pos:[100,0,0] --create a sphere to the right of the teapot
--> $Sphere:Sphere001 @ [100.000000,0.000000,0.000000]

b = box pos:[-50,0,0] --create a box to the left of the teapot
--> $Box:Box001 @ [-50.000000,0.000000,0.000000]

theFile = (GetDir #temp + @"\teapotAndSphere.max") --define a temp file to save
--> "C:\Users\YOURNAME\AppData\Local\Autodesk\3dsMax\2017 - 64bit\ENU\temp\teapotAndSphere.max"

saveNodes #(t,s,b) theFile --save the three objects to the file
--> OK

resetMaxFile #noPrompt --reset the scene again
--> OK

mergeMAXFile theFile #("Teapot001") --attempt to merge two teapots
--> true
m1 = getLastMergedNodes() --check to see what was merged - only one teapot actually exists in the file
--> #($Teapot:Teapot001 @ [0.000000,0.000000,0.000000])

mergeMAXFile theFile #mergeDups #autoRenameDups --merge all objects, allowing duplicates to be renamed
--> true
m2 = getLastMergedNodes() --see what got merged...
--> #($Teapot:Teapot002 @ [0.000000,0.000000,0.000000], $Sphere:Sphere001 @ [100.000000,0.000000,0.000000], $Box:Box001 @ [-50.000000,0.000000,0.000000])

move m2 [0,100,0] --move the objects merged in the second attempt 100 units along Y
--> OK
select m1 --and select the object from the first merge
--> OK

3ds Max Load and Save Dialogs

getMAXSaveFileName [filename:<seed_filename_string>]

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

If the optional filename: string argument is specified and it contains only a file name pattern, only the files matching the pattern will be displayed. If it also contains a file path, the content of the directory matching the pattern will be displayed.

No actual file saving will be performed, only the name of the selected file will be returned. You can perform the saving by passing the result of this function (as long as it is not 'undefined') as argument to saveMaxFile() documented further on this page.

EXAMPLE

--Open the dialog at the current path (can be found or set via sysinfo.currentdir):
theName = getMAXSaveFileName()

--Open the dialog at "c:\temp\" and filter by pattern "test*.max"
--The user must click a specific file if the pattern contains wildcards
theName = getMAXSaveFileName filename:"c:\\temp\\test*.max"

--Open the dialog at "c:\temp\" and set the file name to "test.max"
--The user can click the Open button to get the specified file name if it exists,
--otherwise a prompt will show up saying the file does not exist...
theName = getMAXSaveFileName filename:"c:\\temp\\test.max"
--If the result is not undefined, we can actually save the file:
if theName != undefined do saveMaxFile theName

getMAXOpenFileName [filename:<seed_filename_string>] [dir:<seed_directory_string>]

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

If the optional filename: string argument is specified and it contains only a file name pattern, only the files matching the pattern will be displayed. If it also contains a file path, the content of the directory matching the pattern will be displayed.

If the optional dir: string is specified, the dialog will open at the specified path and the File name field will be set to the current scene file name (found in the maxFileName global variable), or will be empty if the scene is still Untitled.

FOR EXAMPLE.

--Open the dialog at the current path (sysinfo.currentdir):
theName = getMAXOpenFileName()

--Open the dialog at c:\temp and use current file name
theName = getMAXOpenFileName dir:"c:\\temp"

--Open the dialog at "c:\temp\" and filter by pattern "test*.max"
--The user must click a specific file if the pattern contains wildcards
theName = getMAXOpenFileName filename:"c:\\temp\\test*.max"

--Open the dialog at "c:\temp\" and set the file name to "test.max"
--The user can click the Open button to get the specified file name if it exists.
theName = getMAXOpenFileName filename:"c:\\temp\\test.max"

MAX File Object Names

getMAXFileObjectNames <max_filename_string> [quiet:<boolean>] \
  [missingDLLsAction: (#logmsg|#logToFile|#abort|<int>)] [missingDLLsList:<&var array of strings>]

Returns an array of strings, one for each of the names of the objects in the given 3ds Max file. For information about where 3ds Max looks for the specified <max_filename_string>, see Scene File Path Resolution, above.

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: and missing* parameters, 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.

getMaxFileObjects <max_filename_string>  quiet:<true> \
   [ missingDLLsAction:(#logmsg|#logToFile|#abort|<int>) missingDLLsList:<&var array of strings> ]

Gets an array of arrays, containing information about the nodes in the specified <max_filename_string>. Each node information array contains:

1. Node name
2. Node hiearchy level
3. Node handle
4. Node Parent handle

For example:

res = getMaxFileObjects @"C:\My Documents\3ds Max\scenes\armor.max"
#(#("Box001", 1, 3L, 0L), #("PhotometricLight001", 1, 7L, 0L), #("PhotometricLight002", 1, 8L, 0L))

For information about where 3ds Max looks for the specified <max_filename_string>, see Scene File Path Resolution, above.

For details on the quiet: and missing* parameters, see Quiet Mode

Save MAX File

<boolean>saveMaxFile <filename_string> [saveAsVersion:<integer>] [clearNeedSaveFlag:<boolean>] [useNewFile:<boolean>] [quiet:<boolean>]

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.

The optional keywords are true by default to match the existing behavior prior to 3ds Max 6, except when saving as a previous version in 3ds Max 2011 and higher where the useNewFile: is assumed false to prevent the previous version file from becoming the current file.

In 3ds Max 2011 and higher, if a valid previous version is specified using saveAsVersion: , the scene will be saved in the file format of the specified previous version. In 3ds Max 2011 the valid value is 2010. In 3ds Max 2012, the valid values are 2010 and 2011. Any other value will save using the current version's format.

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, 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.

Set Scene File Name

<boolean> setCurrentSceneFileName <filename_string>

NEW in 3ds Max 2024.1 Update Sets the current scene file name to the specified string, and returns true on success, false on failure.

The filename must be a valid name and end with the ".max" suffix, or an empty string. If an empty string is supplied, the scene is named "Untitled" and the user is prompted for a file name and location if they select File > Save.

The filename may be simply a file name, or a fully qualified path. If only a filename is supplied, the file is saved in the 3ds Max install directory by default.

If the scene file name is set using this function, it is considered modified and getSaveRequired() will return true.

Example:

fname= GetDir #scene + "\\teapot.max"
-->"C:\My Documents\max scenes\teapot.max"
setCurrentSceneFileName fname
-->true
getSaveRequired()
-->true

Archive MAX File

<boolean> archiveMAXFile <filename_string> [quiet:<boolean>] [saveAsVersion: <integer>]
    [missingExtFilesAction: (#logmsg|#logToFile|#abort|<int>)] [missingExtFilesList:<&var array of strings>]

Archives the current scene file and all of its related texture maps to a ZIP archive with the specified filename string. Available in 3ds Max 2019.1 Update and higher.

If quiet is true, the Missing Asset dialog will not be displayed if assets are missing.

The saveAsVersion parameter specifies the version of 3ds Max for which the saved archive is compatible. If not specified, the current 3ds Max version is used.

The missingExtFilesAction and missingExtFilesList parameters determine the behavior when assets are missing. For details on the quiet and missing* parameters, see Quiet Mode.

Hold and Fetch

holdMaxFile()

Equivalent to the 3ds Max Edit > Hold operation.

fetchMaxFile [quiet:<boolean>]
    [missingDLLsAction: (#logmsg|#logToFile|#abort|<int>)] [missingDLLsList:<&var array of strings>]
    [missingXRefsAction:(#logmsg|#logToFile|#abort|<int>)] [missingXRefsList:<&var array of strings>]

Equivalent to the 3ds Max Edit > Fetch operation. For details on the quiet and missing* parameters, see Quiet Mode.

Checking For MAX File

<boolean>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.

For information about where 3ds Max looks for the specified <filename_string>, see Scene File Path Resolution, above.

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

Importing Files

importFile <filename_string> [#noPrompt] [quiet:<boolean>] [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 DXF for .dxf , 3DS DOS for .3ds , etc.

The way 3ds Max looks for the specified <filename_string> is the same as for loading scene files. For more information, see Scene File Path Resolution, above.

The #noPrompt flag prevents any configuration or control dialogs from being displayed in which case the default configuration is used. The quiet:<boolean> argument does the same thing, and overrides the #noPrompt option if both are specified.

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:

EXAMPLES:

print importerPlugin.classes

RESULT:

3D_Studio
3D_Studio_Shape
Adobe_Illustrator_Shape
AutoCADImport
FBXIMP
DAEIMP
STL_Import
ATF_Solidworks_importer
Revit_importer
FileLinkAsDwgImporter
ObjImp
Alembic_Import
VrmlImp
ImportTRC
XMLImp2
FltImport
ATF_ProE_importer
ImportHTR
InventorImport
LandXML___DEM_Model_Import
sketchUp
ATF_STEP_importer
SATImport
ATF_IGES_importer
ATF_Alias_importer
ATF_CATIA_V4_importer
ATF_CATIA_V5_importer
ATF_UG_NX_importer
ATF_JT_importer

See also the Import and Export Filters topic for MAXScript access to the settings of some Importer and Exporter plugins.

Exporting Files

exportFile <filename_string> [#noPrompt] [quiet:<boolean>] [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. The quiet:<boolean> argument does the same thing, and overrides the #noPrompt option if both are specified.

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

If the optional using: keyword argument 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
-->#(3D_StudioExporterPlugin, Adobe_Illustrator, DWG_ExportExporterPlugin, DWG_Export, STL_Export,
--  Alembic_Export, ACIS_SAT, PhysX_and_APEX_Exporter, FBXEXP, DAEEXP, IGES_Export, OpenFltExport,
--  ArnoldSceneSourceExport, ObjExp, ExportHTR, AsciiExp, SvfExporter, VRBL_Export, DWF_Exporter)

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.

See also the Import and Export Filters topic for MAXScript access to the settings of some Importer and Exporter plugins.

Saving Nodes

<boolean>saveNodes <node_collection> <filename_string> [saveAsVersion: <integer>] [quiet:<boolean>]

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.

Available in 3ds Max 2011 and higher: If saveAsVersion: provides a value of 2010, the resulting file will be saved in the specified version's file format. Versions prior to 3ds Max 2010 are not supported. If any other value is specified, or if not specified at all, the current version's file format will be used.

For details on the quiet: option which was added to this method in 3ds Max 8, 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.

Check For Save

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.

The function returns false if the user selects "Cancel", true if the user selects to save and the scene was successfully saved, the user selects "Don't Save", or if the scene does not need to be saved. The function also returns true if 3ds Max is running in quiet mode. The file is saved if the user selects "Save".

See also getSaveRequired() in Exiting and Resetting3ds Max.

b = box()
saveNodes b "foo.max"
saveNodes b "foo.max"
saveMaxFile "foo.max"
--All these calls will overwrite the file "foo.max"
--without notice.

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
)

USING THE ABOVE FUNCTIONS:

maybe_saveNodes b "foo.max"
maybe_saveNodes b "foo.max"
maybe_saveMaxFile "foo.max"