Command System: Executing Scripts

From The Foundry MODO SDK wiki
Jump to: navigation, search

Scripts and Macros are executed through the script.implicit or script.run commands. The @ syntax provides a shortcut to script.implicit.

The @ Syntax

Executing a script is done most easily through the @ syntax, followed by the script hash (or other unique identifier, such as a filename, depending on the interpreter used) and any arguments. For example, both of these execute the Unit Sphere config-based macro. Since there is a space in the name, quotes or curly braces need to be used.:

@"Unit Sphere"
@{Unit Sphere}

Scripts on disk can also be executed with this syntax:

@c:MyScript.lxm

If you omit the script and simply enter @, a file dialog will open to select a script to run.

Passing Arguments to Scripts

A script that takes arguments may provide them after the script name, similar to command arguments. Argument parsing is specific to the scripting language, and different syntaxes may apply to different languages. Everything after the script's hash is considered arguments:

@c:MyScript.lxm firstArgument "another argument"

script.implict and script.run

The @ syntax is a shortcut for the script.implicit command.

 script.implicit <name:string> <args:string>
 script.implicit "C:MyScript.lxm" {firstArgument "another argument"}

script.run is similar, but it takes the name of the scripting interpreter that should be used to execute the script. script.implicit infers the service from the script itself.

script.run <name:string> <args:string:
script.run "macro.textscriptinterpreter:c:MyScript.lxm" {firstArgument "another argument"}

Note that since a colon is used as part of the command's first argument's value, the entire argument must be wrapped in curly braces, quotes or square braces so that the script service is not interpreted as an argument name.

In general, script.implicit or the more common @ syntax is used to execute a script, and the script interpreter to use is automatically resolved from the script itself. The script.run command is only used in rare cases where the interpreter must be directly specified.

Paths to Scripts

Scripts on disk can be referenced by absolute path or relative path. Absolutes paths contain drive identifiers, such as the example above.

Relative paths contain only the filename of the script, and possibly the partial path to that filename, but without the root-level anchoring of a drive identifier. When one of these is encountered, the the script system will scan all the <import> paths found in the config. These paths are used to load other config resource files, such as the standard resources in the modo resrc directory. The installer also creates User Configs and User Scripts directories where you can put your own configs and scripts.

You can have as many <import> paths as you like by adding them to your user config or any other imported config. The format is quite simple: just put the absolute path to the directory to be imported in the import tag.

For example, if this line was added to the top of your user config:

<import>C:MyScripts</import>

then the next time you run modo, C:MyScripts will be used to load config files and will be scanned for whenever you execute a script with a relative path. See the config files article for more information on using configs.

Script paths can also include path aliases. This is commonly used for scripts found in Kits.

Installing Custom Scripts

Most scrips and plug-ins should make use of Kits, which allows everything to be bundled up in a single package. It is also possible to manually install scripts without a kit. This is useful for limited distributions, when testing and during development, but in general you should try to use kits when possible.

The first instinct seems to be to put new scripts in the modo installation directory. This is not advised, as you should assume that anything in that directory can change at any moment and without warning.

Instead, you should use the User Configs and User Scripts directories described above. You can find the path to these by entering the following in the Command Entry.

query platformservice path.path ? user

See the ScriptQuery: platformservice documentation for more information on that service, including a list of default user paths on Windows and OS X.

To go directly to those directories, you can choose Open User Configs Folder or Open User Scripts Folder from the System menu in modo. Open User Folder will go to the parent directory containing the other two.

Generally speaking, you'll put your scripts into the User Scripts directory, and your related configuration files (such as custom forms for your script) into the User Configs directory. However, it really doesn't matter which directory they are put in -- both are import paths, so both will be scanned for plug-ins and scripts. The two separate folders are provided merely for convenience, and you can safely put either type of file in either directory.

Scripts can then be executed with the @ syntax as normal. Since the user directories are in the script search path, they will automatically be found.

@MyScript.pl

You can create sub-directories within the user directories as well. Just be sure that when executing the script you also add the sub-directory to the path.

 @MySubDir/MyScript.pl

More Information