getLights: Difference between revisions

Latest revision as of 19:00, 14 March 2023

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, id)
getLights(type, delim, id, 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 ",".
id - The token id of the token to change 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.

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 2: / Line 2: @@
 |name=getLights
 |version=1.3b48
-|description=Returns a string list containing the names of the [[Map:light source{{!}}light source]]s that are on for the [[Current Token]]. The type of the value returned depends on the delimiter parameter.
+|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.
-* If the delimiter is not specified then a [[Macros:string list{{!}}string list]] is returned with the default value of ',' is used.
-* If the delimiter ''"json"'' then a [[JSON Array]] is returned.
-* Otherwise a [[Macros:string list{{!}}string list]] is returned with the delimiter passed in.
 |usage=
-<source lang="mtmacro" line>
+<syntaxhighlight lang="mtmacro" line>
 getLights()
-</source>
-<source lang="mtmacro" line>
 getLights(type)
-</source>
-<source lang="mtmacro" line>
 getLights(type, delim)
-</source>
+getLights(type, delim, id)
-Where
+getLights(type, delim, id, mapname)
-* 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.
+</syntaxhighlight>
-* 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.
+'''Parameters'''
+{{param|type|The light source type, (e.g. "Generic", "D20"). If set to "*", all light sources are returned. Defaults to "*".}}
+{{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 ",".}}
+{{param|id|The token {{code|id}} of the token to change the light sources, defaults to the [[Current Token]]. {{TrustedParameter}} }}
+{{param|mapname|The name of the map to find the token.  Defaults to the current map.}}
 |examples=
-To get a [[Macros:string list{{!}}string list]] of all of the [[LightSource:light source]]s that the current [[Token:token{{!}}token]] has on.
+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.
-<source lang="mtmacro" line>
+<syntaxhighlight 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=
-* '''1.3b49''' - Added ''"json"'' delimiter option.
+{{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]]