Macros

‘’’Macros’’’ are the simplest kind of script. They are simple linear lists of Command System that are executed in order. If any command fails for any reason, the entire macro is aborted. Macros can take arguments, but they cannot perform branching or loops.

One of the easiest ways to create a macro is to use the Macro Recorder. Simply turn it on and start using the application, and all the actions will be recorded in a script up to the maximum number of undos available. The macro can be replayed, saved to disk or stored in the config. Saved macros serve as an excellent starting point for creating new scripts.

File vs. Config Macros

Macros can exist either as their own discrete files, or as part of a configuration file. Both act identically; they only difference is where they’re stored.

File Macros

‘’’File macros’’’ are simple ASCII text files, usually with the extension ‘’.lxm’’, although this is not strictly required.

Comments

The number sign (#) character can also be used to insert comments into the script. It must be at the beginning of a line, without any leading white space. Blank lines are automatically skipped. Any other line is considered a command and will be executed by the macro interpreter.

Example Macro: MyMaterial.lxm

This simple macro changes the name of the selected material to ‘’MyMaterial’’.

1
2
3
4
5
6
7
 1) #LXMacro#
 2)
 3) # Set the name of the selected material to MyMaterial
 4) material.name MyMaterial
 5)
 6) # Switch to "item" selection mode.
 7) select.typeFrom "item"

Executing a File Macro

If this script was saved in ‘’C:MyMaterial.lxm’’, it could be executed with the Command System: Executing Scripts, just like any other script.

1
 @d:\MyMaterial.lxm

Upon execution, the selected material would be renamed to ‘’MyMaterial’’, and the selection mode would be switched to ‘’material’’.

Config Macros

Config macros are similar to file macros, but these are stored in the config file. Both macros are executed the same way and support the same features.

Config Format

This is the macro to create a unit sphere, which can be found in ‘’resource:macros.cfg’’

1
2
3
4
5
6
7
8
9
 <atom type="Macros">
     <hash type="Macro" key="Unit Sphere (Thu Jan 15 10:03:09 2004)">
         <atom type="UserName">Unit Sphere</atom>
         <list type="Command">tool.set &amp;quot;prim.sphere&amp;quot; &amp;quot;on&amp;quot; &amp;quot;0&amp;quot;</list>
         <list type="Command">tool.reset &amp;quot;prim.sphere&amp;quot;</list>
         <list type="Command">tool.apply</list>
         <list type="Command">tool.set &amp;quot;prim.sphere&amp;quot; &amp;quot;off&amp;quot; &amp;quot;3246712&amp;quot;</list>
     </hash>
 </atom>

Config Files are XML files, which requires all the quotes in the commands to be replaced with ‘’&amp;quot’’; There is an outermost Macros block can contain any number of Macro hashes, each having a unique key. Here, the key ‘’Unit Sphere (Thu Jan 15 10:03:09 2004)’’ was derived from the script?s username and the current data and time, but anything can be used as long as its unique and contains legal characters. These Macro hashes define each config macro.

A Macro hash block contains a UserName atom, which is used to display a human-readable name in the Command History Viewport#Scripts.

The remainder of the block contains Command list entries. Each of these contains a single command to execute. As mentioned before, the quotes have been replaced with &amp;quot; for XML compliance.

Executing Config Macros

Config macros are executed with the ‘’@ syntax’’, just like file macros. Since they exist in config files, they can?t be referenced by filename. Instead, a config macro is executed by using either it?s username or, preferably, it?s unique hash. Here there are spaces in both the name and the hash, so we need to wrap them in quotes or curly braces.

1
2
 @"Unit Sphere"
 @"Unit Sphere (Thu Jan 15 10:03:09 2004)"

Imported versus User Config Macros

There are two kinds of Config Files: User and ‘’Imported’’. An Imported config is one that ships with modo, or is otherwise loaded from a config referenced by an <import> directive in another config. User macros exist in your own user config.

Where a config macro is loaded from determines if it can be edited (renamed and deleted) or not. Since changes are only saved to your user config, only macros stored in the user config can be edited from the ‘’Command History?s’’ Scripts tab. Imported macros will have locks on their icons in the Scripts tab.

Arguments

Macros support arguments, which are used as simple substitutions. These are in the form of a percent sign followed by a number, starting from ‘’1’’, such as ‘’%1’’, ‘’%2’’, ‘’%3’’, etc. %1 will be replaced with the first argument, %2 the second, and so on. Anything else following a % is ignored. %% will be replaced with a single ‘’%’’.

Example Macro: Wrapping material.name

We can make our material script into a simple wrapper for material.name using a ‘’%1’’. Note the curly braces we used around the ‘’%1’’.

1
2
3
4
5
6
7
 1) #LXMacro#
 2)
 3) # Set the name of the selected material to %1
 4) material.name %1
 5)
 6) # Switch to "item" selection mode.
 7) select.typeFrom "item"

If this script was saved in ‘’C:RenameMaterial.lxm’’, it could be executed like so.

1
 @d:\RenameMaterial.lxm "New Name"

Upon execution, %1 is replaced with ‘‘“New Name”’’, including the quotes. This causes material.name command is fired as such:

1
 material.name "New Name"

Note that the %1 can be anywhere outside a comment and it will be replaced; it need not be in the argument portion of a command string.