Macro installation (MAXScript)

From Tech Artists Wiki

Jump to: navigation, search

Macros in 3dsmax are somewhat confusing to install and setup. Hopefully this article will illuminate some of the murky areas.

Contents

Terminology

Part of the confusion has to do with terminology. A 'macro' is any script that begins with the MacroScript keyword. For example,

MacroScript myTestMacro
category:"My Macros"
(
)

However, these don't need to be a simple list of commands (as the name 'macro' would imply)- they can be entire tools and very large scripts. There is really no limit. Anything you assign to a button, hotkey, quad menu, etc., is a Macro. You can still run scripts that are not macros by going to Maxscript->Run Script. Macro files generally end with .mcr, and generic maxscript files end with .ms. However, this distinction is not really useful for user scripts, since the file types are treated the same by Max.

Bobo's History Notes:

Historically speaking, MacroScripts were initially introduced to accommodate the MacroRecorder output in 3D Studio MAX R3 in 1999. Just like in Maya, the user was supposed to drag the code emitted by the MacroRecorder from the magenta pane of the Listener to a toolbar and this would automagically generate an MCR file with the content AND automatically encapsulate the code into the MacroScript name ( ) block. The main purpose of the MacroScript was to be placeable in the UI, so it provided several optional keywords and event handlers to define the appearance of the button (and in Max 4 and higher, the menu/quadmenu item).

Of course, users could create their own MacroScripts (as Discreet/Autodesk did, too) and nowadays almost all MacroScripts are hand-written, but the behaviors described on this page including the auto-copying into a folder etc. come from this initial concept.

User Macros

There is a more specific type of Macro, called a user macro. These macros are installed in the user directory. In 3dsmax 8 and earlier, this was the directory

C:/Program Files/Autodesk/3dsmax #/ui/macroscripts/

In 3dsmax 9 and later, the user macros are installed into the directory

C:\Documents and Settings\USER\Local Settings\Application Data\Autodesk\3dsmax\# - 32bit\enu\UI\usermacros

This is inside a couple hidden folders, so you will need to be able to view hidden folders. It is pretty insane to store the macros here, as opposed to My Documents, but oh well. That is why this tutorial was written.

Also note that this behavior can be switched off in 3ds Max on Windows XP so the user data would not be stored in the user's Local Settings but inside the 3dsmax folder srtucture in Program Files. The above behavior was introduced to satisfy Vista's requirement where no user data can be written in the Program Files tree. The usermacros folder was also introduced because of Vista for exactly the same reason - 3ds Max could install the ui\macroscripts content shipping with the package, but the access restrictions would make it impossible to save user-defined Macros there. It is important to note that if the same MacroScript definition is found in both \ui\macroscripts and usermacros, the latter will take precedence. Also, if you open a standard Autodesk-supplied MCR file for editing or debugging, in 3ds Max 9 and higher you will be prompted that a copy of the script will be placed in \usermacros to hold your changes. Thanks to the higher priority of that folder, your edits will overwrite the shipping version.

Other Script Types

There are other script types, such as scripted plugins and utilities. Generally, these are all treated the same, while Macro's are the exception. These are collectively called 'scripts' as opposed to 'macros.'

Installation

When you close Max, it forgets lots of things. It forgets all your macros, it forgets variables you may have made, it forgets the data from any scripts that may have been run. However, when Max starts up, it runs (or evaluates) certain directories. You can find the exact evaluation order in the maxScript help file (under the heading Startup Scripts), but generally it goes something like:

  • /stdplugs/stdscripts/
  • user-defined paths
  • /ui/macroscripts/
  • /scripts/startup/
  • /usermacros/

In order to use your Macro, the code must be in one of these directories. However, one very important thing and the source of much confusion:

MAX AUTO-INSTALLS MACROS

When you evaluate a Macroscript, Max takes all the code in the Macroscript, and makes a file for it in the usermacros directory. Get that? This has ramifications for truly removing a macro, as described later. This also means, you NEVER want to put a macroscript you make or download into /usermacros/ directory, since it really should be for auto-generated macros only.

However, there is an important gotcha here. Let's say you write a macroscript, that includes some functions outside of the macro, that are used in the macro (and, for the sake of code reuse, other places). They are not included in the /usermacros/ file, and when you exit and restart max, those functions are not in Max's memory. Which means, if you try to use the Macro, it will crash, because those functions are undefined.

How You Should Install

What you really want to do is not rely on the /usermacros/ directory at all. Nor the /ui/macroscripts/ directory, quite honestly. Any scripts you write, and plan to edit in the future (which should be ALL the scripts you write) should be evaluated on startup. You are better off putting a script into your /scripts/startup/ folder that will include or fileIn all of your .ms and .mcr files. This way, you will be sure everything you need is evaulated properly. For example, if you have some 'commonFunctions.ms' file that a bunch of macros refer to, this must be evaluated before any macros are run by the user, or they will crash. Best way to do this is by evaluating on startup with a script. This is also true of plug-ins, utilities, etc. They MUST be evaluated by a new session of Max before they can be used.

Review So Far

So, to review this extremely confusing chain of events:

  • Max copies your Macroscript code, and only your Macroscript code, to its /usermacros/ directory.
  • In order to use macros, functions, scripted plugins, etc., they must be evaluated each Max session.
    • This is taken care of for Macros because they are copied to the /usermacros/ directory, but you should not rely on this for any custom macros.
  • Any custom macros and scripts should be evaluated on startup by placing them, or a script that references them, into the /scripts/startup/ directory.

Sample

C:\Program Files\Autodesk\3ds Max 2008\Scripts\Startup\robg3d_scriptLoader.ms

scriptsDir = getDir #scripts
getMacros = getFiles (scriptsDir + "\\robg3d\\robg3d*.mcr")
for f in getMacros do
(
	fileIn f
)

getMacros = getFiles (scriptsDir + "\\robg3d\\robg3d*.ms")
for f in getMacros do
(
	fileIn f
)

This will get all the .mcr and .ms files in the folder C:\Program Files\Autodesk\3ds Max 2008\Scripts\robg3d\ and evaluate them. I don't have to worry about my /usermacros/ directory ever.

Other Things to Add

Try adding the following to your own script loader, and feel free to add your own ideas.

Random Splashscreen Loader

This will choose a random splashscreen fromm a directory, and copy it over the existing splashscreen. The next time the user starts max, they will get the new splashscreen. The change actually happens after Max starts (when the script is run).

try
(
	rootDir = getDir #maxRoot
	bmpArr = getFiles (rootDir  + "Scripts\\robg3d\\splashScreens\\*.bmp")
	chooseNum = random 1 bmpArr.count
	try (deleteFile (rootDir + "\\splash.bmp")) catch ()
	copyFile (bmpArr[chooseNum]) (rootDir + "\\splash.bmp")
) catch ()

Icon Replacer

--get array of all bmp icons, delete old, copy new

  iconsArr = getFiles (scriptDir + "*.bmp")
  for i in 1 to iconsArr.count do
  (
     iconFileName = getFilenameFile iconsArr[i]
     --copy from version control to max path
     --we may also need to delete from the /Local Settings/ user path, add if needed
     iconsDir = "C:\\Program Files\\Autodesk\\3ds Max 9\\ui\\Icons\\"
     deleteFile (iconsDir + iconFileName + ".bmp")
     copyFile (iconsArr[i]) (iconsDir + iconFileName + ".bmp")
  )

Uninstalling/Removing Macros

Remembering what was stated earlier about how scripts don't persist in memory, and how macros are copied to /usermacros/, we can uninstall macros completely by deleting them from /usermacros/ and not re-evaluating them when Max launches (taking them out of our startup script). You'll have to remove the buttons and whatnot by hand though, but no longer will they show up in your Customize User Interface area.

Personal tools