js:MTScript
This article describes a feature or macro function that is experimental and may be subject to change.
Within the javascript environment used by js.eval
, MTScript
is the entry point for interacting with mtscript variables and macros.
MTScript.abort() Function
Note: This function can only be used in a Trusted Macro
• Introduced in version 1.9.4
Similar to the abort() macro, but accepts no arguments. Immediately halts macro execution with no message.
Usage
MTScript.abort()
Parameters
throws
- AbortFunctionException
MTScript.mtsAssert;() Function
Note: This function can only be used in a Trusted Macro
• Introduced in version 1.9.4
Like the assert() macro.
Usage
MTScript.mtsAssert(check, message, pad=true)
Parameters
check
Value to check: iftrue
, do nothing.message
Message to include in the error ifcheck
is false.pad
If true, wrap the error in a localized error string.throws
AssertFunctionException ifcheck
is false.
MTScript.evalMacro;() Function
Note: This function can only be used in a Trusted Macro
• Introduced in version 1.9.4
Run a mtscript macro in the current macro context.
Usage
MTScript.evalMacro(macro)
Parameters
macro
String to run as a macro.return
Any mtscript type.
MTScript.execMacro;() Function
Note: This function can only be used in a Trusted Macro
• Introduced in version 1.9.4
Run a mtscript macro in a new macro context. This is similar to
evalMacro
, except variables from the previous macro context are unavailable, and changes to mtscript variables from within this macro are discarded when the macro exits.Usage
MTScript.execMacro(macro)
Parameters
macro
String to run as a macro.return
Any mtscript type.
MTScript.getMTScriptCallingArgs;() Function
Note: This function can only be used in a Trusted Macro
• Introduced in version 1.9.4
Returns the arguments passed to js.eval() as a list.
Usage
MTScript.getMTScriptCallingArgs()
Parameters
return
list of arguments passed to the current js.eval() call.
MTScript.registerMacro;() Function
Note: This function can only be used in a Trusted Macro
• Introduced in version 1.10.0
Registers a javascript function as a MT UDF under the js. prefix.
Usage
MTScript.registerMacro(macroName, callable)
Parameters
macroName
Name for the new UDF. Note that "js." will be prepended to the name.callable
Any javascript callable.
Example
Using
MTScript.registerMacro
.
function yell(str) {
MapTool.chat.broadcast(str.toUpperCase());
}
MTScript.registerMacro("yell", yell);
[h: js.yell("hello world")]
Output:
HELLO WORLD