getTokens: Difference between revisions
(Added light condition) |
No edit summary |
||
Line 33: | Line 33: | ||
*** <u>note</u>: '''GMs will be able to see everything, to test if a token is visible to a player with this function, you must have "Show as a Player" enabled. In addition, this appears to only affect the "Visible to players" flag - VBL and Fog of War do not seem to affect this'''. | *** <u>note</u>: '''GMs will be able to see everything, to test if a token is visible to a player with this function, you must have "Show as a Player" enabled. In addition, this appears to only affect the "Visible to players" flag - VBL and Fog of War do not seem to affect this'''. | ||
** {{code|layer}} - A JSON array of layer names, or a single layer name as a string. Only tokens on one of the listed layers will be returned. By default, tokens on the Token and Hidden layers are returned.(added in '''1.3b77''') | ** {{code|layer}} - A JSON array of layer names, or a single layer name as a string. Only tokens on one of the listed layers will be returned. By default, tokens on the Token and Hidden layers are returned.(added in '''1.3b77''') | ||
** {{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. | ||
Line 129: | Line 130: | ||
{{change|1.3b55|Added {{code|metric}} option to {{code|range}} option in {{code|conditions}} parameter.}} | {{change|1.3b55|Added {{code|metric}} option to {{code|range}} option in {{code|conditions}} parameter.}} | ||
{{change|1.5.5|Add {{code|propertyType}} option to {{code|conditions}}.}} | {{change|1.5.5|Add {{code|propertyType}} option to {{code|conditions}}.}} | ||
{{change|1.5.7|Add {{code|light}} | {{change|1.5.7|Add {{code|light}} and {{code|mapName}} options to {{code|conditions}}.}} | ||
}} | }} | ||
[[Category:Find Function]] | [[Category:Find Function]] | ||
[[Category:Token Function]] | [[Category:Token Function]] |
Revision as of 22:25, 31 October 2019
getTokens() Function
Note: This function can only be used in a Trusted Macro
Usage
getTokens()
getTokens(delim)
getTokens(delim, conditions)
Parameters
delim
- The delimiter used to sepearate 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. 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.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. 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
- If the token must be owned by the current player, set totrue
(1
) orfalse
(0
).visible
- If the token must be visible to players, set totrue
(1
) orfalse
(0
).- note: GMs will be able to see everything, to test if a token is visible to a player with this function, you must have "Show as a Player" enabled. In addition, this appears to only affect the "Visible to players" flag - VBL and Fog of War do not seem to affect this.
layer
- A JSON array of layer names, or a single layer name as a string. Only tokens on one of the listed layers will be returned. By default, tokens on the Token and Hidden layers are returned.(added in 1.3b77)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: token parameter cannot be unset or empty unless 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: ids = getTokens()]
[foreach(id, ids, "<br>"): id]
- Find ALL the tokens on ALL the layers on the map:
[r:getTokens(",", json.set("{}", "layer", json.append("[]","TOKEN","HIDDEN","OBJECT","BACKGROUND")))]
- Find and return a JSON Array containing all NPC tokens that are with 2 squares or hexes of the selected token:
[h: cond = '{ "range": {"upto":2, "distancePerCell":0, "token":"' +getSelected()+ '"}, "npc":1}']
[h: ids = getTokens("json", cond)]
- Modifying the above example to exclude dead tokens:
[h: cond = '{ "range": {"upto":2, "distancePerCell":0, "token":"' +getSelected()+ '"}, "npc":1, "unsetStates":["Dead"] }']
[h: ids = getTokens("json", cond)]
- Get all of the non dead NPC tokens 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: ids = getTokens("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: ids = getTokens("json", cond)]
Simplest form of getting Tokens with Light sources
[r: getTokens("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 = getTokens("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 = getTokens("json", cond)]
Tokens with Generic light sources.
[h: cond = '{ "light": {"value":1, "category":"Generic"}}']
[r: names = getTokens("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 you JSON object 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's 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 is met because you e.g. used '' or "" where you should not have.
Version Changes
- 1.3b49 - Added
json
delimiter option. - 1.3b51 - Added
conditions
parameter. - 1.3b55 - Added
metric
option torange
option inconditions
parameter. - 1.5.5 - Add
propertyType
option toconditions
. - 1.5.7 - Add
light
andmapName
options toconditions
.