broadcast: Difference between revisions

Latest revision as of 23:59, 14 March 2023

broadcast() Function

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

• Introduced in version 1.3b77

Sends a message in the chat area to either all connected MapTool clients (default), or a subset of player names and/or keywords like "gm" given in a string list or JSON array. Broadcast does not display the sender's name or token image in front of the message.

The big differences between broadcast and a normal chat message are:

if the message is part of a macro, then the message is sent even if the macro is aborted (after the broadcast),
the message sender's name and token image are NOT displayed, and
if you broadcast an execLink(), then that macro is AUTOMATICALLY executed on the clients it's broadcasted to, with the exception of the client that sends the message!

Usage

 broadcast(message, [targets], [delimiter])

Parameters

message - a message that is broadcasted to the users that are listed as parameters.
targets - a String list or JSON array of Player names, not Token names. Also recognizes: "gm", "gm-self", "self", "none", "all", "not-gm", "not-self", and "not-gm-self" as valid parameters. Defaults to all players (so if no parameter is given the message is send to all players). Note that targets is inclusive, so setting it to "not-gm, gm" will send the message to all connected players - all non-GMs and all GMs.
delim - The delimiter used to separate the values in the String List that is given, defaults to ",". If "json" is specified, a JSON array is expected instead of a String List.

Examples

Sending a message to all players:

[h: broadcast("Hello World")]

Sending a message to all GMs only:

[h: broadcast("Hello World", "gm")]

Sending a message to "tim" and "tom" only (default comma delimiter):

[h: broadcast("Hello World", "tim, tom")]

Using json as the delimiter:

[h: broadcast("Hello World", '["tim", "tom"]')]

or

[h: broadcast("Hello World", json.append("", "tim", "tom"))]

Executing the macro update() located at lib:Token, for the token Dragon on the PC of user Tim:

[h: link = macroLinkText("update@Lib:Token", "none", "", "Dragon")]
[h: broadcast(execLink(link), "tim")]

Version Changes

1.5.5 - Added the gm-self, self, all, and none options to targets.
1.5.7 - Added the not-gm-self, not-self, and not-gm options to targets.

@@ Line 5: / Line 5: @@
 |version=1.3b77
 |description=
-This function lets send you a message directly to the chat area of another/all connected maptool clients. It does not display the senders name or token image in front of the message.
+Sends a message in the chat area to either all connected MapTool clients (default), or a subset of player names and/or keywords like {{code|"gm"}} given in a string list or JSON array. Broadcast does not display the sender's name or token image in front of the message.
-It lets send you a message either to all or a list of players - use the player names or the keyword "gm". As delimiter you can specify either a string list separator character or "json" if you specify the target list as json array. The big difference between a 'normal' chat message is: 1. if the message is part of a macro then the message is send even if the macro is aborted(after the broadcast). 2. the sender of the message is NOT displayed and 3. if you broadcast an {{func|execLink}} then that macro is AUTOMATICALLY executed on the clients its broadcasted to, with the exception to the client that sends the message!
+The big differences between broadcast and a normal chat message are:
+#  if the message is part of a macro, then the message is sent even if the macro is aborted (after the broadcast),
+#  the message sender's name and token image are NOT displayed, and
+#  if you broadcast an {{func|execLink}}, then that macro is AUTOMATICALLY executed on the clients it's broadcasted to, with the exception of the client that sends the message!
+&nbsp;
 |usage=
-<source lang="mtmacro" line> broadcast(message, [targets], [delimiter]) </source>
+<syntaxhighlight lang="mtmacro" line> broadcast(message, [targets], [delimiter]) </syntaxhighlight>
 [[Category:Miscellaneous Function]]
 '''Parameters'''
 {{param|message|a message that is broadcasted to the users that are listed as parameters.}}
-{{param|targets|are the user names (so not token names) but the names of the users that are logged in. "gm" is also a valid parameter to give. E.g.: "tim, tom, tarra". Defaults to all players (so if no parameter is given the message is send to all players).}}
+{{param|targets|a String list or JSON array of Player names, not Token names.  Also recognizes: "gm", "gm-self", "self", "none", "all", "not-gm", "not-self", and "not-gm-self" as valid parameters. Defaults to all players (so if no parameter is given the message is send to all players). Note that {{code|targets}} is inclusive, so setting it to "not-gm, gm" will send the message to all connected players - all non-GMs and all GMs.}}
 {{param|delim|The delimiter used to separate the values in the String List that is given, defaults to {{code|","}}. If {{code|"json"}} is specified, a JSON array is expected instead of a String List.}}
-|example=
+|examples=
+&nbsp;
 *Sending a message to all players:
-<source lang="mtmacro" line>
+<syntaxhighlight lang="mtmacro" line>
 [h: broadcast("Hello World")]
-</source><br />
+</syntaxhighlight><br />
-*Sending a message to gm only:
+*Sending a message to all GMs only:
-<source lang="mtmacro" line>
+<syntaxhighlight lang="mtmacro" line>
 [h: broadcast("Hello World", "gm")]
-</source><br />
+</syntaxhighlight><br />
-*Sending a message to tim and tom only:
+*Sending a message to "tim" and "tom" only (default comma delimiter):
-<source lang="mtmacro" line>
+<syntaxhighlight lang="mtmacro" line>
 [h: broadcast("Hello World", "tim, tom")]
-</source><br />
+</syntaxhighlight><br />
-*Using the json as delimiter:
+*Using json as the delimiter:
-<source lang="mtmacro" line>
+<syntaxhighlight lang="mtmacro" line>
 [h: broadcast("Hello World", '["tim", "tom"]')]
-</source> or
+</syntaxhighlight> or
-<source lang="mtmacro" line>
+<syntaxhighlight lang="mtmacro" line>
 [h: broadcast("Hello World", json.append("", "tim", "tom"))]
-</source><br /><br />
+</syntaxhighlight><br />
-*Executing the macro 'update()' located at 'lib:Token', for the token 'Dragon' on the PC of user 'Tim':
+*Executing the macro {{code|update()}} located at {{code|lib:Token}}, for the token {{code|Dragon}} on the PC of user {{code|Tim}}:
-<source lang="mtmacro" line>
+<syntaxhighlight lang="mtmacro" line>
 [h: link = macroLinkText("update@Lib:Token", "none", "", "Dragon")]
 [h: broadcast(execLink(link), "tim")]
-</source><br />
+</syntaxhighlight><br />
+|changes=
+{{change|1.5.5|Added the {{code|gm-self}}, {{code|self}}, {{code|all}}, and {{code|none}} options to  {{code|targets}}.}}
+{{change|1.5.7|Added the {{code|not-gm-self}}, {{code|not-self}}, and {{code|not-gm}} options to  {{code|targets}}.}}
 }}
-===Using the Bag of Tricks===
-Now usually in a macro you would like to use the execution on user pc to happen for those users that 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 function which are on the [http://forums.rptools.net/viewtopic.php?f=46&t=16066 Bag of Tricks (BoT)]. If you have the BoT installed then the following functions are available to you:
-====bot_execAllPlayers()====
-bot_execAllPlayers (macroNname, arguments[, players, output to])
-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.
-{{param|macroName|name of the macro to execute|e.g. runThisMacro@lib:token}}
-{{param|arguments|the arguments to pass on to that macro (in the form of an json array)}}
-{{param|players|a list of PLAYER names where to execute on (so not their token names). Defaults to all players}}
-{{param|output to|Send resulting output of macro to whom (self, gm, all, none, gm-self, list). Defaults to 'none'}}
-''Examples use:''
-*Executing the macro 'update()' located at 'lib:Token', with the parameters "Hello World" and "2" on the PC of user 'Tim', output the result to all:
-<source lang="mtmacro" line>
-[h: bot_execAllPlayers("update@lib:Token", json.append("","Hello World", 2), "Tim", "all")]
-</source><br />
-*The same but now for all players
-<source lang="mtmacro" line>
-[h: bot_execAllPlayers("update@lib:Token", json.append("","Hello World", 2), bot_all(), "all")]
-</source><br />
-The bot_all() is also  a bag of tricks function that returns the names of all players that are logged in. See below for more info.
-====bot_message()====
-If you want to use a different message format, one is availalbe through this functions.
-*{{code|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):
-{{param|message|The message displayed}}
-{{param|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'}}
-{{param|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'.}}
-{{param|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().}}
-{{param|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}}
-{{param|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}}
-{{param|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:''
-<source lang="mtmacro" line>[resultMsg = bot_message('Hello world', 'Header', 'black-white', bot_all(), 'Wolf', '', 0)]</source>
-<source lang="mtmacro" line>[bot_message("Hellow world")]</source>
-<source lang="mtmacro" line>[bot_message("this message is shown to gm only", "GM Only", "red-yellow", bot_gm())]</source>
-<source lang="mtmacro" line>[bot_message("this message is shown to all but gm", "The rest", "yellow-red", bot_ngm())]</source>
-[[Image:Example_Message.jpg]]
-<source lang="mtmacro" line>[h:bot_message(token.name+" Takes damage", "is attacked","red-white",bot_all(),"Dragon", "Eagle")]</source>
-[[Image:Example_Message2.jpg]]
-The following functions can be used in conjunction with bot_message() and return a JSON ARRAY (e.g. ["Frank","Jim","Suzy"])<br>
-{{param|bot_all()|all users}}
-{{param|bot_gm()|gm(s) only}}
-{{param|bot_ngm()|all but NOT gm(s)}}
-{{param|bot_self()|initiator of the macro}}
-{{param|bot_nself()|all but NOT initiator of the macro}}
-{{param|bot_selfgm()|gm(s) and initiator of the macro}}
-{{param|bot_nselfgm()|all but NOT gm(s) and initiator of the macro}}
-{{param|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.}}
-{{param|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. <br>