defineFunction
This article is a stub, you can help the RPTools Wiki project by contributing content to expand this article.
This article needs: Could use examples of the ignoreOutput and newScope parameters.
defineFunction() Function
Note: This function can only be used in a Trusted Macro
Usage
defineFunction(function, macro)
defineFunction(function, macro, ignoreOutput)
defineFunction(function, macro, ignoreOutput, newScope)
Parameters
function
- The name of the user defined function to be defined.macro
- The name and location of the macro that is called when the user defined function is used.ignoreOutput
- If the defined function should ignore all output and only return the value ofmacro.return
, defaults tofalse
(0
).newScope
- Whether the defined function should create a new variable scope when executed. Defaults totrue
(1
). In the default setting, a function can reference only those variables it sets itself, variables passed to it, and global variables defined in token properties. When set tofalse
(0
), this function may reference variables defined in the calling function.
v_varName
is one practice to insure this doesn't happen and is a good visual indicator that the function shares a scope with the calling function. There is still a risk, however, as the calling function could've defined its variables with the same prefix!Interactions between the ignoreOutput
parameter and the macro.return special variable:
- If the UDF sets the value of macro.return and
ignoreOutput
is0
then any output is the return value and macro.return has the value assigned.
- If the UDF sets the value of macro.return and
ignoreOutput
is1
then the return value is the value assigned to macro.return and macro.return has the value assigned.
- If the UDF has output to chat, macro.return is not set and
ignoreOutput
is0
then that output is the return value and macro.return is empty.
- If the UDF has output to chat, macro.return is not set and
ignoreOutput
is1
then the return value and macro.return are empty.
The following table summarizes how these parameters are used. It assumes that the user-defined function is named UDF
and is invoked as in [var = UDF()]
UDF Code | ignoreOutput
| Output Result | Return Result |
---|---|---|---|
[h: macro.return="abc"]
| 0
| "def" stored in var
| macro.return contains "abc"
|
[h: macro.return="abc"]
| 1
| "abc" stored in var
| macro.return contains "abc"
|
macro.return not setdef
| 0
| "def" stored in var
| macro.return is empty
|
macro.return not setdef
| 1
| var is empty
| macro.return is empty
|
Example
[h: defineFunction("character.heal", "heal@Lib:Character")]
Defines a function character.heal()
which calls heal@Lib:Character
when evoked. Note that in this case there must exist a function called "heal" on a token called "lib:Character". The advantage of using the prefix "lib:" on the token name is that it becomes a "lib:token" which is accessible from ANY map instead of only the map you happen to have active.
Should you pass on any arguments e.g.
[h: character.heal("hello", "hi")]
then these parameters can be accessed inside character.heal()
by using
[h: firstArg = arg(0)]
[h: theOtherOne = arg(1)]
See Also
Version Changes
- 1.3b56 - Added
ignoreOutput
andnewScope
parameter options.