Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add macro function getIllumination() #4267

Merged
merged 8 commits into from
Aug 30, 2023

Conversation

kwvanderlinde
Copy link
Collaborator

@kwvanderlinde kwvanderlinde commented Aug 28, 2023

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:

  • Querying what the user currently sees on the current map.
  • Querying for lumens levels on any map independent of token vision
  • Querying for lumens levels according to the vision of specific tokens.

Possible Drawbacks

Should be none

Documentation Notes

getIllumination() function

Get the lumens level at a given point on a map.

Usage

getIllumination(x, y)
getIllumination(x, y, mapNameOrId)
getIllumination(x, y, mapNameOrId, tokenIds)
getIllumination(x, y, mapNameOrId, json.null)

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. Passing json.null indicates 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:

[r: getIllumination(100, 200)]

To check the illumination of the point (100, 200), without including personal lights or magnifiers:

[r: getIllumination(100, 200, getCurrentMapId(), "[]")]

To check the illumination of the point (100, 200) as if no tokens were currently selected:

[r: getIllumination(100, 200, getCurrentMapId(), json.null)]

To check the illumination of the point (100, 200) including the sight of a token named "Elf" (and no other tokens):

[r: getIllumination(100, 200, getCurrentMapId(), json.append("[]", findToken("Elf"))]

Release Notes

  • Added a new macro function getIllumination(x, y, [mapNameOrId, [tokenIds]])

This change is Reviewable

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 kwvanderlinde changed the title Add macro function getIllummination() Add macro function getIllumination() Aug 28, 2023
@cwisniew cwisniew added this pull request to the merge queue Aug 30, 2023
@cwisniew cwisniew added the feature Adding functionality that adds value label Aug 30, 2023
Merged via the queue into RPTools:develop with commit d335783 Aug 30, 2023
4 checks passed
@kwvanderlinde kwvanderlinde deleted the feature/3565-getIllumination branch August 31, 2023 02:35
@Lector
Copy link

Lector commented Nov 29, 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
Labels
feature Adding functionality that adds value
Projects
Status: Merged
Development

Successfully merging this pull request may close these issues.

3 participants