RSS< Twitter< etc

<< Back To XMesh Index

XMesh Saver MX MAXScript Reference



The XMeshSaverUtils Interface exposes all properties and methods of the XMesh Saver MX plugin.

The XMesh Saver User Interface is written in MAXScript and uses this interface.

You can completely replace the provided UI and functionality and implement new User Interface or new caching tools for your pipeline as you see fit.

To see the list of the properties and methods, type in the MAXScript Listener:

showInterface XMeshSaverUtils



This returns True if the XMeshSaver is holding a valid license, False if not. Note that you do not normally need to hold a license.
Contains the full version string of MeshSaver, e.g. "Version: rev.44572"
Contains the version number string of the MeshSaver, e.g. ""
Contains the root directory of the XMeshSaver plugin, which is two folders up from where the .DLU was loaded, e.g. "C:\Program Files (x86)\Thinkbox\XMeshSaver\MX\"
Contains the settings directory of the XMeshSaver plugin. This is the folder where the configuration data is stored, e.g. "C:\Users\YourUserName\AppData\Local\Thinkbox\XMeshSaver"
Get/set the initial offset of the time step. Default is 0.25.
This is used when evaluating the Velocity channel based on two samples of the mesh. The Initial Offset of 0.25 means that a second mesh will be requested a quarter frame later and compared to the mesh on the full frame. If the two have identical topology (same vertex and face count), the velocities will be extrapolated from these two samples. If the two meshes don't match topologically, the process is repeated by requesting another sample closer to the full frame based on the MeshSaverUtils.TimeStepScale property below. With a default step of 0.5, each new sample will be taken at half distance between the last sample and the full frame.
Get/set the scale of the time step. Default is 0.5.
See MeshSaverUtils.TimeStepInitialOffset for details.
When Material ID mapping is enabled, this default Material ID will be assigned to any faces that do not have a mapping. Material ID mapping is enabled by setting one or more mappings using the SetMaterialIDMapping method.
Get/set the Compression Level - a value between -1 and 1. A value of 0 means no compression, while 1 enables compression. -1 means "factory default" and is equivalent to 1.
Get/set the thread count. Default is your number of CPU threads, up to 4. Set to 1 to disable multi-threading.
Get/set whether to pop up the Log Window on errors (true, default) or not.
Get/set the visibility of the Low Window. Default is false. Setting this property to true will effectively open the Log Window.
Get/set the Logging Level. Zero-based index corresponding to the levels listed in the Log Window - 0=None, 1=Errors, 2=Warnings, 3=Progress, 4=Statistics, 5=Debug
Get/set the array of channel names to save. This is an array of strings.


<void>XMeshSaverUtils.SetSequenceName <value>SequenceName
Sets the sequence base file name to be used when saving. The necessary frame number will be added to the file name as needed. The argument must be a string and point to a directory that must exist when the saving methods are called.
<void>XMeshSaverUtils.SaveMeshToSequence <node>Node <bool>IgnoreEmptyMeshes <bool>IgnoreTopologyChanges <bool>UseObjectSpace <bool>FindVelocity
Saves a single mesh to an XMesh file sequence.
  • The Node argument is the scene object to be saved.
  • The IgnoreEmptyMeshes boolean argument controls whether to fail with an error if a mesh contains no geometry (0 faces and vertices). You should pass this as True most of the time.
  • The IgnoreTopologyChanges boolean argument controls whether to fail with an error if the topology of the object changes (False), or to save the meshes regardless (True). You should pass this as True pretty much always, unless you intend to use the data in an XMesh Modifier as Point Cache and topology may not change.
  • The UseObjectSpace boolean argument defines whether to save the geometry in object space and ignore the node's transforms (True) or to apply the node transformations and save in world space (False). If you intend to replace the original geometry with an XMesh Loader and possibly parent the loader to an existing hierarchy, use True. If you want to place the XMesh Loader at the world origin to match all world space transforms and modifications, use False.
<void>XMeshSaverUtils.SaveMeshesToSequence <node array>Nodes <bool>IgnoreEmptyMeshes <bool>IgnoreTopologyChanges <bool>FindVelocity
Saves one or more meshes to an XMesh file sequence.
  • The Nodes array argument is the list of scene objects to be saved.
  • All other arguments are the same as in XMeshSaverUtils.SaveMeshToSequence()
<void>XMeshSaverUtils.SavePolymesh <node>Node <value>Path <bool>VertsOnly
Save a node to a polygon mesh file.
  • The Node argument is the scene object to be saved.
  • The Path argument is the filename to save the mesh as. .xmesh and .obj files are supported.
  • The VertsOnly argument controls whether to save the entire mesh (False) or just the vertices (True). VertsOnly is typically used to save data for XMeshAnimCache, which is our alternative to Point Cache.
Switches the XMesh Saver into scene rendering mode. As you know, XMeshSaver behaves as a "Mesh Renderer" inside of 3ds Max. This switches the scene to render mode to acquire the render-time geometry for saving. This method should be called before calling one of the SaveMesh(es) methods, and should always have a matching XMeshSaverUtils.SetSceneRenderEnd() after the saving has finished. If not called, the scene will remain in viewport mode and the geometry saved will be the viewport geometry - useful for generating proxy sequences.
This is the counterpart to XMeshSaverUtils.SetSceneRenderBegin(). It should be called after the saving has finished to switch the scene back to viewport mode.
Show the license dialog.
Forces a search for license. If no license could be acquired, the license dialog will pop up.
This releases the current license, if any.
Remove all Material ID mappings, and disable Material ID mapping.
<void>XMeshSaverUtils.SetMaterialIDMapping <node>MeshNode <value>FromMaterialIDList <value>ToMaterialIDList
Set the Material ID mappings for a node.
  • MeshNode the node to set the mapping for.
  • FromMaterialIDList Each Material IDs in this array is mapped to the corresponding ID in the ToMaterialIDList. FromMaterialIDList and ToMaterialIDList must have the same length.
  • ToMaterialIDList See FromMaterialIDList. 
<void>XMeshSaverUtils.LogError <value>Msg
Logs the provided message string as an error with the Log Window.
<void>XMeshSaverUtils.LogWarning <value>Msg
Logs the provided message string as a warning with the Log Window.
<void>XMeshSaverUtils.LogProgress <value>Msg
Logs the provided message string as a progress info with the Log Window.
<void>XMeshSaverUtils.LogStats <value>Msg
Logs the provided message as a statistic info with the Log Window.
<void>XMeshSaverUtils.LogDebug <value>Msg
Logs the provided message as a debug info with the Log Window.
Sets the focus on the Log Window.
<value>XMeshSaverUtils.ReplaceSequenceNumber <value>file <float>frame
Replaces the sequence number in the given file with the specified frame number. If the frame number is a round number, it will be inserted as integer. If it is a floating point number, it will be inserted as float using comma as separator for the decimal part, matching the XMesh sub-frame saving format.
<void>XMeshSaverUtils.SetUserData <value>key <value>value
Stores a user-defined value with the given key and value in the user data buffer. Both the key and the value must be strings at this point. The content of the user data buffer will be stored as Metadata in the .XMESH XML header file on each frame when a sequence is saved to disk.
Returns the user data buffer as an array of sub-arrays with key and value pairs in each sub-array.
<void>XMeshSaverUtils.DeleteUserData <value>key
Deletes the given key from the user data buffer, if it exists. Does nothing if the key does not exist (no errors or warnings).
Clears the user data buffer by removing all keys and value pairs.
<void>XMeshSaverUtils.LoadMetadata <value>filename
Loads the custom data from the specified external XML file (usually saved previously using XMeshSaverUtils.SaveMeshToSequence(), XMeshSaverUtils.SaveMeshesToSequence(), or XMeshSaverUtils.SaveMetadata()).
<void>XMeshSaverUtils.SaveMetadata <value>filename
Saves the current content of the custom data buffer to the specified XML file name.  The metadata is automatically saved in an xmesh file, so you do not normally need to call this function.