getLights: Difference between revisions

Latest revision as of 20:25, 13 May 2024

getLights() Function

• Introduced in version 1.3b48

Returns a string list containing the names of the light sources that are turned on for the Current Token. The type of the value returned depends on the delimiter parameter.

Usage

getLights()
getLights(type)
getLights(type, delim)
getLights(type, delim, tokenRef)
getLights(type, delim, tokenRef, mapname)

Parameters

type - The light source type, (e.g. "Generic", "D20"). If set to "*", all light sources are returned. Defaults to "*".
delim - The delimiter used to separate values in the string list. If set to "json", a JSON Array is returned. Defaults to ",".
tokenRef - Either the token id or Token Name of the token to list the light sources, defaults to the Current Token.
Note: This parameter can only be used in a Trusted Macro.
mapname - The name of the map to find the token. Defaults to the current map.

Token IDs are unique, but Token Names can be duplicated. Using Token Name when more than one token has the same name can produce unexpected results.

Examples

To get a string list of all of the light sources that the current token has on.

[getLights()]

To get a string list of the light sources that the current token has on with the light source type of "Generic".

[getLights("Generic")]

Getting all lights from campaign properties
The information provided by getInfo can be used to extract all light source names defined in the campaign properties. The following provides all names in a JSON Array:

[r: json.path.read(json.get(getInfo("campaign"), "light sources"), ".[*][*]['name']")]

To restrict the query to only one specific type of light sources, you can use the following and replace 'TYPE' with the desired type (note that single quotes are needed for this string, because double quotes are already in use):

[r: json.path.read(json.get(getInfo("campaign"), "light sources"), ".['TYPE'][*]['name']")]

Version Changes

1.3b49 - Added "json" delimiter option.
1.5.4 - Added id and mapname parameter options.

@@ Line 1: / Line 1: @@
-==Function getLights==
+{{MacroFunction
+|name=getLights
+|version=1.3b48
+|description=Returns a string list containing the names of the [[Introduction to Lights and Sights|light source]]s that are turned on for the [[Current Token]]. The type of the value returned depends on the delimiter parameter.
-Returns a string list containing the names of the [[Map:light source|light source]]s that are on for the [[Token:Current Token|Current Token]]. The type of the value returned depends on the delimiter parameter.
+|usage=
-* If the delimiter is not specified then a [[Macros:string list|string list]] is returned with the default value of ',' is used.
+<syntaxhighlight lang="mtmacro" line>
-* If the delimiter ''"json"'' then a [[Macros:json array|json array]] is returned. '''(as of MapTool 1.3b49)'''
+getLights()
-* Otherwise a [[Macros:string list|string list]] is returned with the delimiter passed in.
+getLights(type)
+getLights(type, delim)
+getLights(type, delim, tokenRef)
+getLights(type, delim, tokenRef, mapname)
+</syntaxhighlight>
-===Usage===
+'''Parameters'''
-<source lang="mtmacro" line>
+{{param|type|The light source type, (e.g. "Generic", "D20"). If set to "*", all light sources are returned. Defaults to "*".}}
-[h: lights = getLights()]
+{{param|delim|The delimiter used to separate values in the [[Macros:string list{{!}}string list]]. If set to "json", a [[JSON Array]] is returned. Defaults to ",".}}
-[h: lights = getLights(type)]
+{{param|tokenRef|Either the token [[getSelected|{{code|id}}]] or [[getTokenName|Token Name]] of the token to list the light sources, defaults to the [[Current Token]]. {{TrustedParameter}} }}
-[h: lights = getLights(type, delim)]
+{{param|mapname|The name of the map to find the token.  Defaults to the current map.}}
-[h: lights = getLights("*", delim)]
+{{Note|Token IDs are unique, but Token Names can be duplicated. Using Token Name when more than one token has the same name can produce unexpected results.}}
-</source>
-Where
-* type is the [[LightSource:type |type of light source]] (e.g. "Generic" or "D20"). If it is not specified then all [[LightSource:light source|light source]]s that are on for the [[Token:token|token]] are returned.
-* delim is the delimiter used to separate values in the [[Macros:string list|string list]]. If it is not specified then it defaults to ","
-If you want to specify the delimiter but still want to fetch all of the [[LightSource:type | light source type]]s then you can use the special value "*" for type.
+|examples=
+To get a [[Macros:string list{{!}}string list]] of all of the [[Introduction to Lights and Sights|light source]]s that the current [[Token:token{{!}}token]] has on.
-===Examples===
+<syntaxhighlight lang="mtmacro" line>
-To get a [[Macros:string list|string list]] of all of the [LightSource:light source|]]s that the current [[Token:token|token]] has on.
-<source lang="mtmacro" line>
 [getLights()]
-</source>
+</syntaxhighlight>
-To get a [[Macros:string list|string list]] of the [LightSource:light source|]]s that the current [[Token:token|token]] has on with the [[LightSource:type| lighet source type|]] of "Generic".
+To get a [[Macros:string list{{!}}string list]] of the [[Introduction to Lights and Sights|light source]]s that the current [[Token:token{{!}}token]] has on with the light source type of "Generic".
-<source lang="mtmacro" line>
+<syntaxhighlight lang="mtmacro" line>
 [getLights("Generic")]
-</source>
+</syntaxhighlight>
+'''Getting all lights from campaign properties'''<br>
+The information provided by [[getInfo]] can be used to extract all light source names defined in the campaign properties. The following provides all names in a [[JSON Array]]:
+<syntaxhighlight lang="mtmacro" line>
+[r: json.path.read(json.get(getInfo("campaign"), "light sources"), ".[*][*]['name']")]
+</syntaxhighlight>
+To restrict the query to only one specific type of light sources, you can use the following and replace {{code|'TYPE'}} with the desired type (note that single quotes are needed for this string, because double quotes are already in use):
+<syntaxhighlight lang="mtmacro" line>
+[r: json.path.read(json.get(getInfo("campaign"), "light sources"), ".['TYPE'][*]['name']")]
+</syntaxhighlight>
+|changes=
+{{change|1.3b49|Added ''"json"'' delimiter option.}}
+{{change|1.5.4|Added {{code|id}} and {{code|mapname}} parameter options.}}
+}}
+[[Category:Light Function]]
+[[Category:Token Function]]