MaxScript API

PMStructureInfo
This is the main API struct for Kstudio Managers plugins.
Can be used for adding a custom menu item – see more

GetSelectedItemsInfo IncludeMaps:<bool> IncludeThumbs:<bool> - Returns the Array of struct for Selected Items
IncludeMaps : bool
    Returns the Array of external files, used by item
    (Available for Materials and 3ds Max files(max file must be saved in 3ds max version 2010 or above))
IncludeThumbs:
    Returns a path to file used for preview

Each element has next properties:
Item : String or MAXObject
    Returns a path to file or Material/textureMap
Assets : Array 
    Array of external files, used by item (IncludeMaps must set to true)
Thumbnail : String
    Returns a path to file used for preview (IncludeThumbs must set to true)

RemoveSelection() : void
    Removes Selected Items only from ListView (without any changes for files on HDD!)

Refresh() : void
    Refresh all items in ListView

SaveScreenShot file : void
    Save a screenshot from active viewport to file

CurrentFolder : String
    Returns a path to the current directory (or path to material library file)

ConvertToProxy &objectsArray proxyFileName proxyClass - Convert nodes to single Proxy
objectsArray : Array
    Array of nodes for converting to proxy
proxyFileName : String
    Full path to save newly created proxy ( possible be without extension )	
proxyClass : MAXClass
   classOf of target proxy. 
   Set to undefined for convert to a proxy compatible with active renderer

Incomplete list for some supported proxies
	



Renderer 
classOf of Proxy
 Extension


 V-Ray
 VrayProxy
 .vrmesh


 Mental Ray
 mr_Proxy
 .mib


 Corona
 CProxy
 .cgeo


 Maxwell
 MXSRef
 .mxs


 Octane
 OctaneProxy
 .octprx


 Thea
 TheaProxy
 .mod.thea


 FStorm
 FStormProxy
 .fstormmesh


Redshift
 RedshiftProxy
 .rs


FinalRender
fR_Proxy
 .fpx




Example:

SelectedStruct = PMStructureInfo()

SelectedStruct.CurrentFolder => "C:\Temp\"
SelectedStruct.Refresh()

file = @"C:\Temp\Screen.jpg"
SelectedStruct.SaveScreenShot file

SelectedStruct.RemoveSelection()

selectedItems = SelectedStruct.GetSelectedItemsInfo() 

/* get array of files from selectedItems */
selectedFiles = for item in selectedItems collect item.Item

/* or Array of selected materials from opened Material Library */
selectedMats = for item in selectedItems where superClassOf item.Item == material collect item.Item

/* print array of external files, used by item */
for item in selectedItems do (
    format "%\n" item.Item
    format "Asset Files:\n"
    for file in item.Assets do 
        format "\t%\n" file
)
/*
Result:
"C:\Temp\SomeModel.max"
Asset Files:
  "C:\Temp\Maps\Bitmap_1.jpg"
  "C:\Temp\Maps\Bitmap_2.jpg"
*/

KstudioManagerCategoryAPI struct
KstudioManagerCategoryAPI struct allows to manage categories.
See an example in the file “Manage Categories.ms” in the ‘presets’ directory.

KstudioManagerCategory - struct contains information about category
	Properties:
		Name 		- string Text
		FullPath 	- string FullPath
		ID 		- ID From DataBase
		Section 	- Name of Section  #Models #Materials #Textures #IES
	Methods:
		GetParent 	- returns parent category
		GetNodes 	- returns array of children categories


KstudioManagerCategoryAPI - struct for manage categories

GetCategories()
	Returns all categories with related name in specified section  #Models #Materials #Textures #IES

KstudioManagerCategoryAPI.GetCategories path_string section_name

	
section_name = #Models
path_string = "" 				-- returns all categories from the top level
path_string = "Chair" 			-- returns all categories with related name from all levels
path_string = @"Office\Chair" 	-- returns all categories with name "Chair" and parent "Office"
categories = KstudioManagerCategoryAPI.GetCategories path_string section_name
AddCategory()
	Create and return new category with specified name and specified parent in specfied section
	category_string: Name of Category, string
	parent_integer: Parent ID, integer. Can be 0 for adding to top level
	section_name: name.  #Models #Materials #Textures #IES

	Return: struct KstudioManagerCategory or undefined on unsuccess
	Note: Might return an existing category with the same name at the same level

KstudioManagerCategoryAPI.AddCategory category_string parent_integer section_name
catName = "New Category from API"
newCategory = KstudioManagerCategoryAPI.AddCategory catName categories[1].ID section_name

AssignCategory()
	Assign Category to array of files
	Returns: bool

	parent_integer: Parent ID, integer. Can be 0 for adding to top level
	files_string_array: array of files
	section_name: name.  #Models #Materials #Textures #IES

KstudioManagerCategoryAPI.AssignCategory parent_integer files_string_array section_name
files = getFiles @"*.3ds"
KstudioManagerCategoryAPI.AssignCategory categories[1].ID files section_name

PmCallbacks struct
PmCallbacks struct allows to use callback events.
See example in file "PostFileMerge Example.ms" in 'presets' directory.

The callbacks are added using the following syntax:
PmCallbacks.AddScript <callbackTypeName> <MAXScriptFunction> [CallbackID:<name>]
callbackTypeName - callback event type name.
MAXScriptFunction - maxscript function for using in callback.
The optional CallbackID: parameter lets you tag one or a group of callbacks with a unique name.

Remove callbacks:
PmCallbacks.RemoveScripts [CallbackID:<name>]

Next method lists out the current callback scripts in the Listener window:
PmCallbacks.Show [CallbackID:<name>]

Example:
#postFileMerge:
	CallbackId:#RenameNodesAfterMerge, RenameNodesAfterMerge()
#postFileMerge:
	CallbackId:#ConvertMaterials, ConvertMaterialsAfterMerge()
#postFileMerge:
	CallbackId:#RemoveGroupHeadAfterMerge, RemoveGroupHeadAfterMerge()

	
PmCallbacks Help:
PmCallbacks.ShowHelp()
ShowHelp method prints next information to the Listener window:
PmCallbacks.AddScript <callbackTypeName> <MAXScriptFunction> [CallbackID:<name>]
PmCallbacks.RemoveScripts [callbackTypeName:<name>] [CallbackID:<name>]
PmCallbacks.GetCallbackTypeNames()
#postFileMerge
	Struct:PmPostMergeData
		ParentNode<node>
		Nodes<Array of nodes>
		File<fileName>
		UsePlaceDialog<bool>
#preFileExport
		...


Get currently supported callbackTypeNames:
PmCallbacks.GetCallbackTypeNames()
This method prints all currently supported callbackTypeNames to the Listener window.
 
Example:
Set desired name for merged nodes
Note: place this script to scripts startup directory
With #postFileMerge callbackTypeName use the Struct:PmPostMergeData

fn RenameNodesAfterMerge &PostMergeStruct =
(
	for obj in PostMergeStruct.Nodes where isValidNode obj and not isDeleted obj do
		obj.Name = uniqueName (getFilenameFile PostMergeStruct.File)
)

if (superClassOf PmCallbacks == structDef) do (
	PmCallbacks.removeScripts CallbackID:#RenameNodesAfterMerge
	PmCallbacks.addScript #postFileMerge RenameNodesAfterMerge CallbackID:#RenameNodesAfterMerge
)

Function PMpostFileMerge is deprecated since version 2.94.22.

BatchPostScript
Use this global struct for managing Objects or Materials.

MaxFile:
    Returns a full path to current 3Ds Max file or Material Library
SceneObjects:
    Array of scene objects ( excluding studio's objects )
SkipRender:
    Set to true to skip rendering the current file
GetDescription [filename:<filename_string>]:
    Returns the user-specified description for the file.
UpdateDescription [filename:<filename_string>] [description:<string>]:
    Save new description for file.
GetMode():
    Returns the state of current mode as string: #Unknown, #Render, #BeforeRender, #Relink or #Test
Version:
    Returns the version of used API 
 
Example:
Save a description for 3ds Max file

if BatchPostScript != undefined and pathConfig.appendPath maxFilePath maxFilename == BatchPostScript.MaxFile and BatchPostScript.GetMode() != #Test do (
	
	local sceneObjects = BatchPostScript.SceneObjects
	local numFaces = 0;
	local numVerts = 0;
	for obj in sceneObjects where superClassOf obj == GeometryClass do (
		local objMeshInfo = getPolygonCount obj
		numFaces += objMeshInfo[1]
		numVerts += objMeshInfo[2]
	)
	/* Save Description */
	if( numVerts > 0 ) do (
		/* get existing file's description */
		local currentDescription = BatchPostScript.GetDescription BatchPostScript.MaxFile;
		local description = StringStream ""
		format "%\nFaces: %\nVertices: %" currentDescription numFaces numVerts to:description
		/* Save description */
		BatchPostScript.UpdateDescription BatchPostScript.MaxFile (description as string);
		/* Free Memory */
		free description
		close description
	)
	BatchPostScript.SkipRender = true
)

Example for using GetMode() #BeforeRender:
Rendering from multiply cameras (from version 2.70.xx)

if BatchPostScript != undefined and BatchPostScript.GetMode() == #BeforeRender do (
	local wasCancelled = false
	local sceneObjects = for obj in BatchPostScript.SceneObjects where superClassof obj != camera collect obj
	for c in BatchPostScript.SceneObjects where superClassof c == camera and wasCancelled == false do (
		viewport.SetCamera c
		/* Fit camera focal distance to nodes ( available from version 2.70.xx )*/
		BatchPostScript.FitCameraFov sceneObjects
		
		/* Render using standard Virtual Frame buffer */
		local bm = (render vfb:true renderhiddenobjects:false netrender:false renderType:#normal quiet:false outputSize:[650,650] cancelled:&wasCancelled)
		if ( wasCancelled == false and classOf bm == Bitmap) do (
			bm.filename = BatchPostScript.MaxFile + "_" + c.Name + ".jpg"
			save bm quiet:true
			close bm
			free bm
		)
	)
	/* disable rendering using 'Batch Render&Relink' */
	BatchPostScript.SkipRender = true
)