getTokens: Difference between revisions

Revision as of 06:55, 12 March 2009

This article is a stub, you can help the RPTools Wiki project by contributing content to expand this article.
This article needs: More information on the area condition, and examples that use the newest additions.

getTokens() Function

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

• Introduced in version 1.3b48

Gets a list containing the ids of all the tokens on the current map, or all the tokens that match the specified conditions. The type of the value returned depends on the delimiter parameter.

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.
- unsetStates - A JSON array of states the token must not have.
- npc - If the token must be a NPC, set to true(1) or false(0).
- pc - If the token must be a PC, set to true(1) or false(0).
- selected - If the token must be selected, set to true(1) or false(0).
- impersonated - If the token must be impersonated, set to true(1) or false(0).
- current - If the token must be the current token, set to true(1) or false(0).
- owned - If the token must be owned by a player, set to true(1) or false(0).
- visible - If the token must be visible to players, set to true(1) or false(0).
- 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.
  - distancePerCell - If the Distance Per Cell multiplier should be used, set to true(1) or false(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.
- area - A JSON object.

Example

You can use the following code to print out the ids of all of the tokens on the current map.

[h: ids = getTokens()]
[foreach(id, ids, "<br>"): id]

Version Changes

1.3b49 - Added json delimiter option.
1.3b51 - Added conditions parameter.

@@ Line 1: / Line 1: @@
+{{stub|More information on the area condition, and examples that use the newest additions.}}
 {{MacroFunction
 |name=getTokens
@@ Line 4: / Line 5: @@
 |version=1.3b48
 |description=
-Gets a list containing the ids of all the [[Token:token|token]]s on the current [[Map:map|map]]. The type of the value returned depends on the delimiter parameter.
+Gets a list containing the ids of all the tokens on the current map, or all the tokens that match the specified conditions. The type of the value returned depends on the delimiter parameter.
-* If the delimiter is not specified then a [[Macros:string list|string list]] is returned with the default value of {{code|","}} is used.
-* If the delimiter {{code|json}} then a [[Macros:json array|json array]] is returned.
-* Otherwise a [[Macros:string list|string list]] is returned with the delimiter passed in.
 |usage=
 <source lang="mtmacro" line>
 getTokens()
+</source>
+<source lang="mtmacro" line>
 getTokens(delim)
 </source>
+<source lang="mtmacro" line>
-If {{code|delim}} is specified then it is used to separate the values in the list, if it is not specified then it defaults to {{code|","}}.
+getTokens(delim, conditions)
+</source>
+'''Parameters'''
+{{param|delim|The delimiter used to sepearate 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 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|unsetStates}} - A JSON array of states the token must '''not''' have.
+** {{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|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|current}} - If the token must be the current token, set to {{true}} or {{false}}.
+** {{code|owned}} - If the token must be owned by a player, set to {{true}} or {{false}}.
+** {{code|visible}} - If the token must be visible to players, set to {{true}} or {{false}}.
+** {{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|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|upto}} - A number specifying the maximum range that a token can be from the source.
+** {{code|area}} - A JSON object.}}
 |example=
-You can use the following code to print out the ids of all of the [[Token:token|token]]s on the current [[Map:map|map]].
+You can use the following code to print out the ids of all of the tokens on the current map.
 <source lang="mtmacro" line>
 [h: ids = getTokens()]
@@ Line 25: / Line 44: @@
 |changes=
-* '''1.3b49''' - Added {{code|json}} delimiter option.
+{{change|1.3b49|Added {{code|json}} delimiter option.}}
+{{change|1.3b51|Added {{code|conditions}} parameter.}}
 }}
 [[Category:Find Function]]
-[[Category:Token Function]]