Bag of Tricks
Bag of Tricks
A large collection of macros and resources for MapTool compiled by Wolph42.
You can download the Bag of Tricks from the RPTools forums.
Note that the BoT contains far more material, macros, functions and tools then the below two functions. The BoT also contains a detailed manual with description of all available functions, including these two below. This article was written because from a 'macro function' perspective they are the two most relevant macros that the BoT contains.
Using the automatic remote execution function from Bag of Tricks
Usually in a macro you would like the execution of a macro on the computer of those users who own the token in context. Or maybe you want to execute a macro on ALL clients but you have to figure out who the current 'executer' is and run the macro for that client separately as the execLink() is only executed on remote clients. To make this a bit easier, I've created a couple of functions which are part of the Bag of Tricks (BoT). If you have the BoT installed, then the following functions are available to you:
This macro executes the macro
macroName on ALL SELECTED clients. So in contrast of
broadcast(execLink()), you do not have to worry about who is executing the macro since everyone does.
bot_execAllPlayers (macroName, arguments, [players], [output_to])
macroName- name of the macro to execute; e.g.
arguments- the arguments to pass to the macro (in the form of a JSON array)
players- a list of PLAYER names where to execute on (not token names). Defaults to all players
output to- Send resulting output of macro to whom (
gm-self, list). Defaults to none
- Executing the macro
lib:Token, with the parameters
"2"on the PC of user
Tim, with the output of the result going to all connected systems:
[h: bot_execAllPlayers("update@lib:Token", json.append("","Hello World", 2), "Tim", "all")]
- The same but now for all players
[h: bot_execAllPlayers("update@lib:Token", json.append("","Hello World", 2), bot_all(), "all")]
bot_all() function is another BoT function that returns the names of all players that are logged in. See below for more info.
If you want to use a different message format, one is availalbe through this functions.
bot_message(0:message [, 1:headertxt, 2:color (bgcolor-txtcolor), 3:userList, 4:token, 5:target, 6:broadcast])
Broadcasts a preformatted message to all users (default). The message consists out of a black (bg) and white (txt) header (default) and a delimited textbox below it, containing the message. When the message is left empty () only the header will be displayed. bot_message contains the following optional parameters (only message is required):
message- The message displayed
headerText- This defaults to: . The text in the header, note that the 'token' parameter is set in the header as well on the left side. E.g. when token is 'Wolf' and headerTxt is 'Attacks' the header will read 'Wolf Attacks'
color- This defaults to 'black-white'. Here you can set the backgroundcolor-textcolor of the header. You can choose also to only set the backgroundcolor. Some examples: 'red', 'black-yellow', yellow-red'.
userlist- Defaults to all(). Here you can set to whom the message should be send. You can either fill in a user name yourself (NOT TOKEN NAME!) e.g. 'Frank' or you can make use of one of the user functions defined here below, e.g. all(), gm(), ownergm().
token- Defaults to . Here you can give the name of the token to which the message reflects. The effect is that the image and name of the token appears left in the header
target- Defaults to . Here you can give the name of another token to which the message reflects. The effect is that the image of tha token appears right in the header
broadcast- Defaults to 0 the message is NOT broadcasted but the entire structure is returned. This is usefull is you want to e.g. embed the result in another message; (1) (default) the message is immediately broadcasted
A couple examples of use:
[resultMsg = bot_message('Hello world', 'Header', 'black-white', bot_all(), 'Wolf', '', 0)]
[bot_message("this message is shown to gm only", "GM Only", "red-yellow", bot_gm())]
[bot_message("this message is shown to all but gm", "The rest", "yellow-red", bot_ngm())]
[h:bot_message(token.name+" Takes damage", "is attacked","red-white",bot_all(),"Dragon", "Eagle")]
The following functions can be used in conjunction with bot_message() and return a JSON ARRAY (e.g. ["Frank","Jim","Suzy"])
bot_all()- all users
bot_gm()- gm(s) only
bot_ngm()- all but NOT gm(s)
bot_self()- initiator of the macro
bot_nself()- all but NOT initiator of the macro
bot_selfgm()- gm(s) and initiator of the macro
bot_nselfgm()- all but NOT gm(s) and initiator of the macro
bot_ownergm()- gm(s) and owners of the currentToken. So NOT the token that you might give as a parameter to the bot_message() function but the token that is currentToken() at that moment.
bot_nownergm()- all but NOT gm(s) and owners of the current token
The 'bot_' prefixes in all these function are added as a precaution to make sure that there are no conflicts with a framework in which you use the BoT. If you however want to use these 'retrieve user' functions but without the 'bot_' prefix you need to create your own set of user defined functions.