Add macro function getIllumination() #4267

Until now, a `PlayerView` with an empty token list and a `PlayerView` with a `null` token list were the same, and both would return `true` for `isUsingTokenView()`. We now distinguish these cases to allow token views that happen to not have any tokens, which is useful for excluding illumination contributions from personal lights and sight magnifiers. Existing callers that would pass an empty token list to the `PlayerView(Role, List<Token>)` constructor now call the `PlayerView(Role)` in order to keep the same behaviour.

In rare cases, the current zone renderer can be `null`, and `FunctionUtil.getZoneRendererFromParam()` was not handling this case despite promising never to return `null` itself.

Usage: `getIllumination(x, y)` This basic form of the function uses the current `PlayerView` for the map, so the lumens value returned will match what the lumens overlay shows on the client at the given point. Personal lights and sight magnifiers will be accounted for if they are in the current view.

New usage: `getIllumination(x, y, mapNameOrId)` If `mapNameOrId` is provided, the result will be returned for a point on the provided map. If not provided, the result will be for the current map.

New usage: `getIllumination(x, y, mapNameOrId, tokenIds)` The token list controls allows the player view to be customized. It must be a JSON array of tokens IDs for the current zone, with any unknown tokens resulting in an error. If not provided, the player view will be the current player view for the map. If the list of token IDs is empty, the `PlayerView` will use a token view but with no tokens involved, i.e., no token sight will be accounted for.

New usage: `getIllumination(x, y, mapNameOrId, json.null)` Using `json.null` for this parameter will indicate that a token view will not be used. I.e., the behaviour will match the lighting seen when no tokens are selected on the map.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add macro function getIllumination() #4267

Add macro function getIllumination() #4267

Commits on Aug 28, 2023