Add macro function getIllumination() #4267
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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.
kwvanderlinde
changed the title
cwisniew
approved these changes
Aug 30, 2023
|
I tested this on v1.14.2 and it works fine. Thanks for adding this :) |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Identify the Bug or Feature request
Implements #3565
Description of the Change
This adds a new macro function
getIllumination()that returns the lumens level at a given point on a given map. Whether personal lights and sight magnifiers are included can be controlled via parameters, allowing the function to be used for at least these cases:Possible Drawbacks
Should be none
Documentation Notes
getIllumination() function
Get the lumens level at a given point on a map.
Usage
Parameters
x- The X coordinate to check, measured in pixels.y- The Y coordinate to check, measured in pixels.mapNameOrId- The map to check the illumination of. Defaults to the current map.tokenIds- The tokens IDs whose personal lights and sight magnifiers should contribute to the result. Defaults to those in the current player view. Passingjson.nullindicates that token-specific views should not be used (i.e., as if no tokens were selected on the map).Examples
To check the illumination of the point (100, 200) as seen in the player's current view:
To check the illumination of the point (100, 200), without including personal lights or magnifiers:
To check the illumination of the point (100, 200) as if no tokens were currently selected:
To check the illumination of the point (100, 200) including the sight of a token named "Elf" (and no other tokens):
Release Notes
getIllumination(x, y, [mapNameOrId, [tokenIds]])This change is