[Feature]: Add map parameter for functions that take token ID

[kwvanderlinde]

Describe the Problem

Many macro functions that operate on tokens accept a map name in addition to a token ID/name, but not all do. E.g., getLabel() accepts a token ID, but not a map name, so I can only use it to get the label of a token on the current map. In addition to being inconsistent, this means I have to switch maps just to get information about tokens.

The Solution you'd like

I would like the following functions to be updated to accept a map name / ID parameter:

• [ ] getAlwaysVisible()
• [ ] getDistance()
• [ ] getDistanceToXY()
• [ ] getHalo()
• [ ] getLabel()
• [ ] getOwnerOnlyVisible()
• [ ] getTokenHillVBL()
• [ ] getTokenMBL()
• [ ] getTokenPitVBL()
• [ ] getTokenVBL()
• [ ] getVisible()
• [ ] isVisible()
• [ ] macroLink() (unsure?)
• [ ] macroLinkText() (unsure?)
• [ ] movedOverToken()
• [ ] moveToken()
• [ ] moveTokenFromMap() (to move to somewhere other than current map)
• [ ] moveTokenToMap() (to move from somewhere other than current map)
• [ ] setAlwaysVisible()
• [ ] setHalo()
• [ ] setLabel()
• [ ] setOwnerOnlyVisible()
• [ ] setTokenHillVBL()
• [ ] setTokenMBL()
• [ ] setTokenPitVBL()
• [ ] setTokenVBL()
• [ ] setVisible()
• [ ] transferHillVBL()
• [ ] transferMBL()
• [ ] transferPitVBL()
• [ ] transferVBL()

I'm guessing it also makes sense for these functions, though I've never used the herolab functionality myself:

• [ ] herolab.getImage()
• [ ] herolab.getInfo()
• [ ] herolab.getMasterName()
• [ ] herolab.getStatBlock()
• [ ] herolab.hasChanged()
• [ ] herolab.isMinion()
• [ ] herolab.refresh()
• [ ] herolab.XPath()

The following are some functions that do not need updating despite taking a token name/ID:

• deselectTokens()
• getImage() (can use getTokenImage() instead)
• goto(token) (only meaningful if we switch maps anyways)
• impersonate()
• selectTokens()

Alternatives that you've considered.

Switching maps before getting token properties like the label, then switching back. This is verbose, but otherwise works fine for getters. However, the documentation suggests there are thorns waiting when doing so for setters.

Additional Context

There are many more functions that only operate on the current token and give no option to work on a different token. I could have added those to the list as well, but I wanted to keep this FR somewhat focused.

[Jmr3366]

I was looking to create a getMapID("display name/map name") function to help ease the access to the ID. It seems that many of these functions could be updated to accept map ID as well. https://rptools.hyperbooks.com/index.php/Category:Map_Function

[kwvanderlinde]

@Jmr3366 See #3852. In 1.14, we will have getMapIDs("map name") among a few other new ID-oriented functions, and all map functions that make sense have been updated to accept map IDs in addition to names.

[FullBleed]

Going to bump this one. I keep knocking my head against this as I mapIDify my framework and run into functions that don't support it.

I've been creating some "fake" local versions of some functions where I can pass the mapID, then check it against currentMapID, switch to the right map if it's not the same, run the function, then switch back. It works, but it's slower and hacky.

[bubblobill]

The sensible thing to do would be to only use the map argument on non-unique identifiers, i.e. token names. A token UID should just find the token regardless of where it is.

[FullBleed]

The sensible thing to do would be to only use the map argument on non-unique identifiers, i.e. token names. A token UID should just find the token regardless of where it is.

That would be really nice... would that be a bigger code change than updating these functions?

[FullBleed]

To add to this list:

• [ ] getPCNames()
• [ ] getSpeech()
• [ ] getSpeechNames()

And, I use an impersonate() UDF that takes a mapID (using the hack I mentioned above) because I needed it to have character sheets for tokens on other maps open that impersonate the tokens they are connected to. If I switch maps to do something on another map, and I have the sheet up, some behaviour breaks without my UDF. There are reasons for this that I settled on a long time ago... so if it's not going to "break" impersonate() to get a map ID I'd like to have it.

[Baaaaaz]

getSpeech() getSpeechNames()

Also previously requested here: https://github.com/RPTools/maptool/issues/5038