[Feature]: getIllumination()

[Lector]

Feature Request

In my framework, you can assign multiple types of light/dark-sources to a token. When attacking a token, i want to calculate how bright the target is illuminated and determine a modifier for the attack roll according to this value. Since there are multiple light sources in my campaign with different modifiers i would also like to get the lumens of the illumination or the brightest light source, that is illuminating my target.

The Solution you'd like

I would like to call getIllumination(token) to get the lumens of the brightest light-source or the brightest light-source that is illuminating the token.

Alternatives that you've considered.

Since my framework does not support magical darkness yet, i used to determine the illumination manually with 2 scripts. All my light-sources have 4 Parts in 4 different Radii (e.g. "Torch 1", "Torch 2", "Torch 3", "Torch 4"). The lights are turned on/off by a custom UI so when using a Torch all the technically lights "Torch 1-4" are turned on/off at once. My scripts look like this:

getIllumination(): `[h: target = arg(0)]

[h: info = json.indent(getInfo("map"), 2)] [h: visiontype = json.get(info, "vision type")]

[h,if(visiontype == "NIGHT"),Code: { [h: newTarget = copyToken(target)] [h: tokens = getTokens("json", json.set("", "layer", json.append("[]", "token", "object", "background"), "range", json.set("", "token", newTarget, "from", 0, "upto", 24), "light", json.set("", "value", 1, "category", "DSA") ))] [h: brightness = 4] [h,foreach(tok, tokens),Code:{ [h: newTok = copyToken(tok)] [h: setHasSight(true, newTok)] [h: setSightType("Normal", newTok)] [h: isTargetVisible = json.length(canSeeToken(target, newTok))] [h,if(isTargetVisible > 0): brightness = min(brightness, getBrightnessFrom(target, tok))] [h: removeToken(newTok)] }] [h: removeToken(newTarget)] [h: macro.return = brightness] }; { [h: macro.return = 0] }]`

getBrightnessFrom() `[h: target = arg(0)] [h: illuminator = arg(1)] [h: distance = getDistance(illuminator, 1, target, "NO_GRID")] [h: lights = getLights("DSA", "json", illuminator)] [h: radius = 0] [h: currentLight = ""]

[h,foreach(light, lights),Code:{ [h,if(endsWith(light, "4") == 1 && currentLight == ""): currentLight = light] }]

[h,if(currentLight != ""),Code:{ [h: cmp = json.indent(getInfo("campaign"), 2)] [h: dsalights = json.get(json.get(cmp, "light sources"), "DSA")] [h,foreach(light, dsalights),Code:{ [h: lname = json.get(light, "name")] [h,if(lname == currentLight): radius = json.get(light, "max range")] }] };{}]

[h,if(radius == 0),Code:{ [h: macro.return = 0] };{ [h: width = scale(getSize(target)) / 2.0] [h: steps = (distance - width) / (radius / 4.0)] [h: brightness = max(0, min(4, floor(steps)))] [h: macro.return = brightness] }]`

This works almost fine. One problem occurs when a light-source is not hitting the center or corner of the target. In this case canSeeToken() does not work but thats fine. Whats more problematic is the magical darkness that i wanted to add support for in my framework. I would like to add negative lumen lights for this case. This works well for the visuals in the map. But the calculation of the illumination modifier when attacking a token should get very complicated at this point.

Since maptool should internally know more details about the illumination of a token i think its easier for framework-devs to get a function for all this.

Additional Context

No response