js:MTScript

From RPTools Wiki
Jump to navigationJump to search

 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.10.0
Similar to the abort() macro, but accepts no arguments. Immediately halts macro execution with no message.

Usage

1 MTScript.abort()

Parameters

  • throws - AbortFunctionException


MTScript.mtsAssert;() Function

 Note: This function can only be used in a Trusted Macro

Introduced in version 1.10.0
Like the assert() macro.

Usage

1 MTScript.mtsAssert(check, message, pad=true)

Parameters

  • check Value to check: if true, do nothing.
  • message Message to include in the error if check is false.
  • pad If true, wrap the error in a localized error string.
  • throws AssertFunctionException if check is false.


MTScript.setVariable() Function

 Note: This function can only be used in a Trusted Macro

Introduced in version 1.10.0
Sets an MTScript variable. Like {{{1}}}. For use with MTScript.evalMacro.

Usage

1 MTScript.setVariable(variable, value)

Parameters

  • variable - String, Variable name to set.
  • value - Any javascript object. Value to set.


MTScript.getVariable() Function

 Note: This function can only be used in a Trusted Macro

Introduced in version 1.10.0
Reads an MTScript variable. Counterpart to MTScript.setVariable.

Usage

1 MTScript.getVariable(variable)

Parameters

  • variable - String, Variable name to get.


MTScript.evalMacro;() Function

 Note: This function can only be used in a Trusted Macro

Introduced in version 1.10.0
Run a mtscript macro in the current macro context.

Usage

1 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.10.0
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

1 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.10.0
Returns the arguments passed to js.eval() as a list.

Usage

1 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

1 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.
1 function yell(str) {
2   MapTool.chat.broadcast(str.toUpperCase());
3 }
4 
5 MTScript.registerMacro("yell", yell);


[h: js.yell("hello world")]

Output:

HELLO WORLD



See Also

JS: MapTool