getTokenNames: Difference between revisions
Verisimilar (talk | contribs) No edit summary |
No edit summary |
||
(32 intermediate revisions by 9 users not shown) | |||
Line 1: | Line 1: | ||
{{MacroFunction | {{MacroFunction | ||
|name=getTokenNames | |name=getTokenNames | ||
|trusted=true | |trusted=true | ||
|version=1.3b48 | |||
|description= | |description= | ||
Gets a list containing the names of all the [[Token|token]]s on the current [[ | Gets a list containing the names of all the [[Token|token]]s on the current [[Introduction to Mapping|map]], or all the tokens that match the specified conditions. The type of the value returned depends on the delimiter parameter. This function does not return the IDs of lib:tokens. Note: apparently the order of the list that getTokens() returns is also the z-order of the tokens, where the lowest z-order is the first in the list or array that is returned! | ||
|usage= | |usage= | ||
< | <syntaxhighlight lang="mtmacro" line> | ||
getTokenNames() | getTokenNames() | ||
getTokenNames(delim) | getTokenNames(delim) | ||
getTokenNames(delim, conditions) | getTokenNames(delim, conditions) | ||
</ | </syntaxhighlight> | ||
'''Parameters''' | '''Parameters''' | ||
{{param|delim|The delimiter used to | {{param|delim|The delimiter used to separate the values in the String List that is returned, defaults to {{code|","}}. If {{code|"json"}} is specified, a [[JSON Array]] is returned instead of a String List.}} | ||
{{param|conditions|A JSON | {{param|conditions|A [[JSON Object]] that contains various conditions that the tokens must fullfill. All conditions are optional. | ||
** {{code|setStates}} - A JSON array of states the token must have. | ** {{code|setStates}} - A JSON array of states the token must have or a single state name as a string. Any token which does not contain all of these states in the {{code|true}} condition will be removed from the returned list. | ||
** {{code|unsetStates}} - A JSON array of states the token must '''not''' have. | ** {{code|unsetStates}} - A JSON array of states the token must '''not''' have or a single state name as a string. | ||
** {{code|npc}} - If the token must be a NPC, set to {{true}} or {{false}}. | ** {{code|npc}} - If the token must be a NPC, set to {{true}} or {{false}}. | ||
** {{code|pc}} - If the token must be a PC, set to {{true}} or {{false}}. | ** {{code|pc}} - If the token must be a PC, set to {{true}} or {{false}}. | ||
** {{code|propertyType}} - A JSON array of token types or a single token type as a string. Only tokens of a type included in the array will be returned. | |||
** {{code|selected}} - If the token must be selected, set to {{true}} or {{false}}. | ** {{code|selected}} - If the token must be selected, set to {{true}} or {{false}}. | ||
** {{code|impersonated}} - If the token must be impersonated, set to {{true}} or {{false}}. | ** {{code|impersonated}} - If the token must be impersonated, set to {{true}} or {{false}}. | ||
** {{code|current}} - If the token must be the current token, set to {{true}} or {{false}}. | ** {{code|current}} - If the token must be the current token, set to {{true}} or {{false}}. | ||
** {{code|owned}} - | ** {{code|owned}} - A [[JSON Array]] containing player names. All tokens that have at least one of the listed players as owner will be returned. Alternatively, a string containing '''one''' of the following options: | ||
** {{code|visible}} - If the token | *** {{code|self}} - tokens owned by the current player | ||
*** {{code|notself}} - tokens not owned by the current player | |||
*** {{code|others}} - tokens owned by any player, but not owned by the current player | |||
*** {{code|any}} - tokens owned by any player | |||
*** {{code|none}} - tokens not owned by any player | |||
*** {{code|single}} - tokens owned by a single player | |||
*** {{code|multiple}} - tokens owned by more than one player | |||
*** {{code|byall}} - tokens owned by all players | |||
*** {{code|notbyall}} - tokens not owned by all players | |||
** {{code|visible}} - If the token is visible in the current client's view. Set to {{true}} or {{false}}. | |||
*** When the visible option is used only tokens on the TOKEN layer and which are shown within the client's current map view will be returned. | |||
*** This is not a test of whether or not other tokens on the map out of view are visible to a specific token. See {{func|canSeeToken}}. | |||
*** GMs will be able to see all tokens within the current map view. Players (including View as Player) will only get returned those tokens that are shown in their current map view. Tokens returned will also be affected by server settings like Individual Views. | |||
** {{code|layer}} - A JSON array of layer names, or a single layer name as a string. Note that a token not on any of the listed layers will be removed from the list returned. | |||
** {{code|mapName}} - The name of the map to get the tokens from. Defaults to the current map. | |||
** {{code|range}} - A JSON object with range conditions, all range conditions are optional. | ** {{code|range}} - A JSON object with range conditions, all range conditions are optional. | ||
*** {{code|token}} - The id or name of the source token that the distance is measured from, defaults to the current token. | *** {{code|token}} - The id or name of the source token that the distance is measured from, defaults to the current token. | ||
**** <u>note</u>: this parameter is needed if you are calling your macro from a macroLink and aren't impersonating a token. | |||
*** {{code|distancePerCell}} - If the Distance Per Cell multiplier should be used, set to {{true}} or {{false}}. | *** {{code|distancePerCell}} - If the Distance Per Cell multiplier should be used, set to {{true}} or {{false}}. | ||
*** {{code|from}} - A number specifying the minimum range that a token needs to be from the source. | *** {{code|from}} - A number specifying the minimum range that a token needs to be from the source. | ||
*** {{code|upto}} - A number specifying the maximum range that a token can be from the source. | *** {{code|upto}} - A number specifying the maximum range that a token can be from the source. | ||
** {{code|area}} - A JSON object.}} | *** {{code|metric}} - The distance metric to use, if it is not specified the default from the users preferences is used. | ||
** {{code|area}} - A JSON object containing specific area information. | |||
*** {{code|token}} - An optional field that contain the name or id of the token that resides at the center of the area. Defaults to the current token. | |||
*** {{code|offsets}} - A JSON array of JSON objects that specify each individual cell that make up the area. | |||
**** {{code|x}} - The relative {{code|x}} position of the cell in relation to the {{code|token}} field. Measured in cells. | |||
**** {{code|y}} - The relative {{code|y}} position of the cell in relation to the {{code|token}} field. Measured in cells.}} | |||
** {{code|light}} - Can be a Boolean indicating tokens with any light source (1) or no light sources (0). Alternatively a JSON object with the light specifications with any combination of the following: | |||
*** {{code|value}} - Boolean indicating that the token must have the light(s) specified if true(1). | |||
*** {{code|name}} - The name of the light as given in the Campaign Properties -> Light tab. | |||
*** {{code|category}} - The category of the light as given in the Campaign Properties -> Light tab. | |||
The movement metric in range specifies the movement metric use, the metric can be one of the following strings: | |||
:* {{code|NO_GRID}} - The grid is ignored and straight line distance between the tokens is returned. | |||
:* {{code|ONE_TWO_ONE}} - First Diagonal movement costs 1, second 2, and so on (Square grid only). | |||
:* {{code|ONE_ONE_ONE}} - Diagonal movement costs a single square (Square grid only). | |||
:* {{code|MANHATTAN}} - Diagonal movement costs 2 (Square grid only). | |||
:* {{code|NO_DIAGONALS}} - No diagonal movement is allowed (Square grid only). | |||
|example= | |example= | ||
You can use the following code to print out the names of all of the | *You can use the following code to print out the names of all of the tokens on the current map: | ||
< | <syntaxhighlight lang="mtmacro" line> | ||
[h: names = getTokenNames()] | [h: names = getTokenNames()] | ||
[foreach(name, names, "<br>"): name] | [foreach(name, names, "<br>"): name] | ||
</source> | </syntaxhighlight><br /> | ||
*Find and return a [[JSON Array]] containing all NPC tokens' names that are within 2 squares or hexes: | |||
<syntaxhighlight lang="mtmacro" line> | |||
[h: cond = '{ range: {upto:2, distancePerCell:0}, npc:1 }'] | |||
[h: names = getTokenNames("json", cond)] | |||
</syntaxhighlight><br /> | |||
*Modifying the above example to exclude dead tokens: | |||
<syntaxhighlight lang="mtmacro" line> | |||
[h: cond = '{ range: {upto:2, distancePerCell:0}, npc:1, unsetStates:["Dead"] }'] | |||
[h: names = getTokenNames("json", cond)] | |||
</syntaxhighlight><br /> | |||
*Get all of the non dead NPC tokens' names in the square above, below, left, and to the right of the token, using the {{code|area}} option: | |||
<syntaxhighlight lang="mtmacro" line> | |||
[h: areaOffsets = '[ {x:1, y:0}, {x:0, y:1}, {x:-1, y:0}, {y:-1, x:0}]'] | |||
[h: area = json.set("{}", "offsets", areaOffsets)] | |||
[h: cond = json.set("{}", "area", area, "npc", 1, "unsetState", "['Dead']")] | |||
[h: names = getTokenNames("json", cond)] | |||
</syntaxhighlight><br /> | |||
*The same could be achieved using the {{code|range}} option with {{code|NO_DIAGONALS}} metric: | |||
<syntaxhighlight lang="mtmacro" line> | |||
[h: cond = '{ range: {upto:1, distancePerCell:0, metric:"NO_DIAGONALS"}, npc:1, unsetStates:["Dead"] }'] | |||
[h: names = getTokenNames("json", cond)] | |||
</syntaxhighlight><br /> | |||
*Get ALL tokens on a map: | |||
<syntaxhighlight lang="mtmacro" line> | |||
[r:allToks = getTokenNames(",",'{layer:["TOKEN", "HIDDEN", "OBJECT", "BACKGROUND"]}')] | |||
</syntaxhighlight> | |||
or better: | |||
<syntaxhighlight lang="mtmacro" line> | |||
[r:getTokens(",", json.set("{}", "layer", json.append("[]","TOKEN","HIDDEN","OBJECT","BACKGROUND")))] | |||
</syntaxhighlight> | |||
Simplest form of getting Tokens with Light sources | |||
<syntaxhighlight lang="mtmacro" line> | |||
[r: getTokenNames("json",'{"light":1}')] | |||
</syntaxhighlight> | |||
Getting tokens from the Object layer with a light source. | |||
<syntaxhighlight lang="mtmacro" line> | |||
[h: cond = json.set("", "layer",'["Object"]')] | |||
[h: cond = json.set(cond, "light",'{"value":1}')] | |||
[r: names = getTokenNames("json", cond)] | |||
</syntaxhighlight> | |||
Tokens with torches | |||
<syntaxhighlight lang="mtmacro" line> | |||
[h: cond = json.set("", "layer",'["Token"]')] | |||
[h: cond = json.set(cond, "light",'{"value":1,"name":"Torch - 20","category":"D20"}')] | |||
[r: names = getTokenNames("json", cond)] | |||
</syntaxhighlight> | |||
Tokens with Generic light sources. | |||
<syntaxhighlight lang="mtmacro" line> | |||
[h: cond = '{ "light": {"value":1, "category":"Generic"}}'] | |||
[r: names = getTokenNames("json", cond)] | |||
</syntaxhighlight> | |||
Please Note that it, in general, is bad practice to create json objects and arrays by hand. This makes your code very bug prone. The proper way is to build your json objects through code.<br /> | |||
E.g.: | |||
<syntaxhighlight lang="mtmacro" line> | |||
[h: cond = '{ range: {upto:1, distancePerCell:0, metric:"NO_DIAGONALS"}, npc:1, unsetStates:["Dead"] }'] | |||
</syntaxhighlight> | |||
can better be created with | |||
<syntaxhighlight lang="mtmacro" line> | |||
[h: cond = json.set("{}", "range", json.set("{}", "upto", 1, "distancePerCell", 0, "metric", "NO_DIAGONALS"), "npc", 1, "unsetStates", json.append("[]","Dead"))] | |||
</syntaxhighlight> | |||
The big difference between the two methods is that, doing it by hand, it is quite likely that when you make a mistake your code appears to 'work', that is you get no error reports, but only part of the conditions are met because you e.g. used {{code|<nowiki>''</nowiki>}} or {{code|""}} where you should not have.<br /> | |||
If you make a mistake in the automated method, there is a bigger chance you get an error report, allowing you to fix it. Of course typos like {{code|'ragne'}} instead of {{code|'range'}} won't trigger any errors. | |||
|changes= | |changes= | ||
{{change|1.3b49| | {{change|1.3b49|Add {{code|json}} delimiter option.}} | ||
{{change|1.3b51| | {{change|1.3b51|Add {{code|conditions}} parameter.}} | ||
{{change|1.3b55|Add {{code|metric}} option to {{code|range}} option in {{code|conditions}} parameter.}} | |||
{{change|1.3b77|Add {{code|layer}} option to {{code|conditions}}.}} | |||
{{change|1.5.5|Add {{code|propertyType}} option to {{code|conditions}}.}} | |||
{{change|1.5.7|Add {{code|light}} and {{code|mapName}} options to {{code|conditions}}.}} | |||
{{change|1.5.8|Add more options to {{code|owned}}.}} | |||
|also= | |||
{{func|getTokens}} | |||
}} | }} | ||
[[Category:Token Function]] | [[Category:Token Function]] | ||
[[Category:Find Function]] |
Latest revision as of 17:00, 20 April 2023
getTokenNames() Function
Note: This function can only be used in a Trusted Macro
Usage
getTokenNames()
getTokenNames(delim)
getTokenNames(delim, conditions)
Parameters
delim
- The delimiter used to separate the values in the String List that is returned, defaults to","
. If"json"
is specified, a JSON Array is returned instead of a String List.conditions
- A JSON Object that contains various conditions that the tokens must fullfill. All conditions are optional.setStates
- A JSON array of states the token must have or a single state name as a string. Any token which does not contain all of these states in thetrue
condition will be removed from the returned list.unsetStates
- A JSON array of states the token must not have or a single state name as a string.npc
- If the token must be a NPC, set totrue
(1
) orfalse
(0
).pc
- If the token must be a PC, set totrue
(1
) orfalse
(0
).propertyType
- A JSON array of token types or a single token type as a string. Only tokens of a type included in the array will be returned.selected
- If the token must be selected, set totrue
(1
) orfalse
(0
).impersonated
- If the token must be impersonated, set totrue
(1
) orfalse
(0
).current
- If the token must be the current token, set totrue
(1
) orfalse
(0
).owned
- A JSON Array containing player names. All tokens that have at least one of the listed players as owner will be returned. Alternatively, a string containing one of the following options:self
- tokens owned by the current playernotself
- tokens not owned by the current playerothers
- tokens owned by any player, but not owned by the current playerany
- tokens owned by any playernone
- tokens not owned by any playersingle
- tokens owned by a single playermultiple
- tokens owned by more than one playerbyall
- tokens owned by all playersnotbyall
- tokens not owned by all players
visible
- If the token is visible in the current client's view. Set totrue
(1
) orfalse
(0
).- When the visible option is used only tokens on the TOKEN layer and which are shown within the client's current map view will be returned.
- This is not a test of whether or not other tokens on the map out of view are visible to a specific token. See canSeeToken().
- GMs will be able to see all tokens within the current map view. Players (including View as Player) will only get returned those tokens that are shown in their current map view. Tokens returned will also be affected by server settings like Individual Views.
layer
- A JSON array of layer names, or a single layer name as a string. Note that a token not on any of the listed layers will be removed from the list returned.mapName
- The name of the map to get the tokens from. Defaults to the current map.range
- A JSON object with range conditions, all range conditions are optional.token
- The id or name of the source token that the distance is measured from, defaults to the current token.- note: this parameter is needed if you are calling your macro from a macroLink and aren't impersonating a token.
distancePerCell
- If the Distance Per Cell multiplier should be used, set totrue
(1
) orfalse
(0
).from
- A number specifying the minimum range that a token needs to be from the source.upto
- A number specifying the maximum range that a token can be from the source.metric
- The distance metric to use, if it is not specified the default from the users preferences is used.
area
- A JSON object containing specific area information.token
- An optional field that contain the name or id of the token that resides at the center of the area. Defaults to the current token.offsets
- A JSON array of JSON objects that specify each individual cell that make up the area.x
- The relativex
position of the cell in relation to thetoken
field. Measured in cells.y
- The relativey
position of the cell in relation to thetoken
field. Measured in cells.
light
- Can be a Boolean indicating tokens with any light source (1) or no light sources (0). Alternatively a JSON object with the light specifications with any combination of the following:value
- Boolean indicating that the token must have the light(s) specified if true(1).name
- The name of the light as given in the Campaign Properties -> Light tab.category
- The category of the light as given in the Campaign Properties -> Light tab.
The movement metric in range specifies the movement metric use, the metric can be one of the following strings:
NO_GRID
- The grid is ignored and straight line distance between the tokens is returned.ONE_TWO_ONE
- First Diagonal movement costs 1, second 2, and so on (Square grid only).ONE_ONE_ONE
- Diagonal movement costs a single square (Square grid only).MANHATTAN
- Diagonal movement costs 2 (Square grid only).NO_DIAGONALS
- No diagonal movement is allowed (Square grid only).
Example
[h: names = getTokenNames()]
[foreach(name, names, "<br>"): name]
- Find and return a JSON Array containing all NPC tokens' names that are within 2 squares or hexes:
[h: cond = '{ range: {upto:2, distancePerCell:0}, npc:1 }']
[h: names = getTokenNames("json", cond)]
- Modifying the above example to exclude dead tokens:
[h: cond = '{ range: {upto:2, distancePerCell:0}, npc:1, unsetStates:["Dead"] }']
[h: names = getTokenNames("json", cond)]
- Get all of the non dead NPC tokens' names in the square above, below, left, and to the right of the token, using the
area
option:
[h: areaOffsets = '[ {x:1, y:0}, {x:0, y:1}, {x:-1, y:0}, {y:-1, x:0}]']
[h: area = json.set("{}", "offsets", areaOffsets)]
[h: cond = json.set("{}", "area", area, "npc", 1, "unsetState", "['Dead']")]
[h: names = getTokenNames("json", cond)]
- The same could be achieved using the
range
option withNO_DIAGONALS
metric:
[h: cond = '{ range: {upto:1, distancePerCell:0, metric:"NO_DIAGONALS"}, npc:1, unsetStates:["Dead"] }']
[h: names = getTokenNames("json", cond)]
- Get ALL tokens on a map:
[r:allToks = getTokenNames(",",'{layer:["TOKEN", "HIDDEN", "OBJECT", "BACKGROUND"]}')]
or better:
[r:getTokens(",", json.set("{}", "layer", json.append("[]","TOKEN","HIDDEN","OBJECT","BACKGROUND")))]
Simplest form of getting Tokens with Light sources
[r: getTokenNames("json",'{"light":1}')]
Getting tokens from the Object layer with a light source.
[h: cond = json.set("", "layer",'["Object"]')]
[h: cond = json.set(cond, "light",'{"value":1}')]
[r: names = getTokenNames("json", cond)]
Tokens with torches
[h: cond = json.set("", "layer",'["Token"]')]
[h: cond = json.set(cond, "light",'{"value":1,"name":"Torch - 20","category":"D20"}')]
[r: names = getTokenNames("json", cond)]
Tokens with Generic light sources.
[h: cond = '{ "light": {"value":1, "category":"Generic"}}']
[r: names = getTokenNames("json", cond)]
Please Note that it, in general, is bad practice to create json objects and arrays by hand. This makes your code very bug prone. The proper way is to build your json objects through code.
E.g.:
[h: cond = '{ range: {upto:1, distancePerCell:0, metric:"NO_DIAGONALS"}, npc:1, unsetStates:["Dead"] }']
can better be created with
[h: cond = json.set("{}", "range", json.set("{}", "upto", 1, "distancePerCell", 0, "metric", "NO_DIAGONALS"), "npc", 1, "unsetStates", json.append("[]","Dead"))]
The big difference between the two methods is that, doing it by hand, it is quite likely that when you make a mistake your code appears to 'work', that is you get no error reports, but only part of the conditions are met because you e.g. used ''
or ""
where you should not have.
'ragne'
instead of 'range'
won't trigger any errors.See Also
Version Changes
- 1.3b49 - Add
json
delimiter option. - 1.3b51 - Add
conditions
parameter. - 1.3b55 - Add
metric
option torange
option inconditions
parameter. - 1.3b77 - Add
layer
option toconditions
. - 1.5.5 - Add
propertyType
option toconditions
. - 1.5.7 - Add
light
andmapName
options toconditions
. - 1.5.8 - Add more options to
owned
.