getTokenNames: Difference between revisions

Revision as of 00:13, 23 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.

getTokenNames() Function

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

Gets a list containing the names of all the tokens on the current map.

Usage

getTokenNames()

getTokenNames(delim)

getTokenNames(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 names of all of the tokens on the current map.

[h: names = getTokenNames()]
[foreach(name, names, "<br>"): name]

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=getTokenNames
 |trusted=true
 |description=
-Gets a list containing the names 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 names of all the [[Token|token]]s on the current [[Map|map]].
-* 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>
-[h: names = getTokenNames()]
+getTokenNames()
-[h: names = getTokenNames(delim)]
+</source>
+<source lang="mtmacro" line>
+getTokenNames(delim)
+</source>
+<source lang="mtmacro" line>
+getTokenNames(delim, conditions)
 </source>
+'''Parameters'''
-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|","}}.
+{{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=
@@ Line 24: / Line 43: @@
 |changes=
-* '''1.3b49''' - Added {{code|json}} delimiter option.
+{{change|1.3b49|Added {{code|json}} delimiter option.}}
+{{change|1.3b51|Added {{code|conditions}} parameter.}}
 }}
 [[Category:Token Function]]