[#1546] Add enricher that rolls items

[MaxPat931]

A refresh of #2626 for 3.0 and closes #1546

Updated how the token/actor is gathered when given a Relative Id when the link is in the new Chat Cards as well as the Tooltips on the new Actor sheets.

Item Enrichers

Item enrichers allow you to use an item from an enriched link. There are several different methods to create an Item enricher, which will determine how the item is used:
By Item Name:
[[/item Bite]]
This functions similarly to a system macro, as if you have dragged that item to the macro hotbar. When clicked on it will check for a selected token, or your assigned actor, if a the found token or actor has an item of a matching name, it will be used, if the found token or actor does not have an item of that name, a warning will be displayed.

By UUID:
[[/item Actor.p26xCjCCTQm5fRN3.Item.amUUCouL69OK1GZU]]
A UUID contains references to an Actor and an Item it owns. When clicked on, the enricher will find the specified Actor and use the specified Item.

By Relative ID:
[[/item amUUCouL69OK1GZU]]
[[/item .amUUCouL69OK1GZU]]
[[/item .Bite]]
A Relative ID can contain a reference to an owned Item either by an Id, a relative Id (note the preceding .), or by name (again, note the preceding .). When clicked on the enricher will use its location (either in an Actor Sheet, Item Sheet, or Chat Card) to determine the Token or Actor that owns that card or sheet to use the specified item from that owner.

[Fyorl]

I don't think we should support this custom UUID syntax. Mixing names with IDs complicates this code considerably, and also does not handle things like compendium UUIDs or synthetic Actor UUIDs. By not using fromUuid it also means it will not benefit from future improvements such as foundryvtt/foundryvtt#10301, or any changes made to UUIDs in general.

I would suggest we just support a single level name lookup that simply called actor.items.getName, as well as UUIDs and relative UUIDs via fromUuid.

[MaxPat931]

Mixing the names with IDs does complicate the code a bit, but it is more user friendly since it's easy to see at a glance the actor and item names, not all users know how to get the UU/IDs, even though its just a quick press of the button

Im not sure why we would want to support Compendium UUIDs, as there isnt a current method to use an item from a compendium (there was even an issue where use from the compendium was possible and it was closed as a bug #2350 )

I dont really know what a synthetic actor UUID is used for tbh, so, how would a user actually get/use that to create one of these enrichers on their actor/token actor?

Why use actor.items.getName instead of dnd5e.documents.macro.rollItem?

I havent really been able to figure out how to get fromUuid to work with a relative id at all and I couldnt find anything in the discord that worked. So for instance, importing an Aboleth, it's Tentacle should have a UUID of Actor.rfsMPNRV4EcZL5Gj.Item.sgauK8Lyt8qxsxOH could you give me an example of how to use fromUuid with the item's relative UUID of .sgauK8Lyt8qxsxOH?

[Fyorl]

Mixing the names with IDs does complicate the code a bit, but it is more user friendly since it's easy to see at a glance the actor and item names, not all users know how to get the UU/IDs, even though its just a quick press of the button

I appreciate it's more user-friendly but I don't think we should support an entirely separate UUID scheme of our own invention, and only in one place. Let's start with actual UUIDs for now.

I dont really know what a synthetic actor UUID is used for tbh, so, how would a user actually get/use that to create one of these enrichers on their actor/token actor?

Unlinked tokens have UUIDs that look like this: Scene.IbFluxE7rYKZ6qXr.Token.ICIMDrbXo6qGD7xE.Actor.4IkQE3RWi7nkzVKD. It can be obtained in exactly the same way as any other Actor UUID, just from the sheet of an unlinked token, rather than a linked one.

Why use actor.items.getName instead of dnd5e.documents.macro.rollItem?

Doesn't macro.rolIItem require having a token selected? I may be misunderstanding, but if I have one of these Item enrichers on an Actor sheet, shouldn't clicking it roll it with the Actor whose sheet it is, rather than with the selected token?

I havent really been able to figure out how to get fromUuid to work with a relative id at all and I couldnt find anything in the discord that worked. So for instance, importing an Aboleth, it's Tentacle should have a UUID of Actor.rfsMPNRV4EcZL5Gj.Item.sgauK8Lyt8qxsxOH could you give me an example of how to use fromUuid with the item's relative UUID of .sgauK8Lyt8qxsxOH?

The UUID of ".sgauK8Lyt8qxsxOH" would be relative to one of the Aboleth's other Items. The UUID of the Tentacle Item relative to the Aboleth is ".Item.sgauK8Lyt8qxsxOH". You can generate the UUID of some Document relative to another Document with Document#getRelativeUUID.

// This returns the Tentacle Item.
fromUuid(".Item.sgauK8Lyt8qxsxOH", { relative: aboleth });

[MaxPat931]

Ok, I was able to take another pass at it, removing "Name UUID" support and adding better UUID handling including synthetic actor items UUIDs. I did keep in the two methods for Names, the "Relative Name" [[/item .Bite]] which always resolves to the parent Token/Actor when in an owned item, and the regular "Name" [[/item Bite]] which uses the macro.rollItem because I do find it useful to be able to use one enricher in a journal or popped out chat card to Bite with all 12 zombies in an encounter. and it doesnt add much to the code.

[Fyorl]

and the regular "Name" [[/item Bite]] which uses the macro.rollItem because I do find it useful to be able to use one enricher in a journal or popped out chat card to Bite with all 12 zombies in an encounter.

Ah I think I just didn't understand the use-case for this. But if it's in chat or a journal with no parent Actor context, then that makes sense. If you invoke macro.rollItem with 12 selected zombies does it roll 12 attacks, or just 1? It will be important to tweak the functionality Jeff is proposing below:

What I'm thinking is we have a single style without the leading period, and when it is clicked we first look at the selected token(s) and search them for an item of that name, activating the first one found. If no item exists on the selected actors, we search the actor upon which the item resides to see if the item exists there (this could also be reversed to check the actor upon which the description exists first, and then check selected tokens).

This seems like a reasonable idea. We get the best of both worlds without having to 'hard-code' whether the reference is relative or not.

[MaxPat931]

If you invoke macro.rollItem with 12 selected zombies does it roll 12 attacks, or just 1?

It will attempt the roll from the most recently selected token, which is how the macro functions if you drag an item to the hotbar, and also consistent with the other enrichers

we first look at the selected token(s) and search them for an item of that name, activating the first one found. If no item exists on the selected actors, we search the actor upon which the item resides to see if the item exists there (this could also be reversed to check the actor upon which the description exists first, and then check selected tokens).

Which of these is the "right" order here? I think the first one makes more sense to me, but I am not sure

[MaxPat931]

Ok I was able to update the Relative ID methods to using relativeTo and refactor the Name method to function as discussed, first attempt to use an item of the given name on the selected token, then if no token selected falling back to the assigned actor, then finally the Actor that owns the item the enricher is in (if it's in an item or chat card of an item)

[MaxPat931]

I've made some changes due to the feedback, the logic for the Name rolling I hope is a bit simpler: For Enrichers in a Sheet owned by an actor (actor sheet, tooltip, item sheet, item chat card)

• If used by the Owner of the parent Actor it will check if a token is selected and has an item of that name, if so use that item, else use the parent's item of that name (and throw a warning if the Parent does not have an item of that name, or selected token was bypassed for not having an item of that name)
• If used by a Non-Owner, use the macro method (this prevents the enricher from acting differently for non-owners depending on if they have their token selected or not)

For enrichers not in an Actor owned Sheet (Journal, Rolltable result, typed into chat)

• Use the Macro method

I know you wanted to get away from the macro method, but using it saved me from identifying token/actor and repeating the warnings

~~However, I did keep in the testUserPermission checks, as getting rid of them leads to non-owners being able to use the items for some reason...~~ Nothing to see here

Oh, and these should also be excluded from the work in #3356 imo

[MaxPat931]

Thanks for the feedback Kim, unfortunately I dont have the bandwidth to continue with this at the moment, @arbron would you mind finishing this off?

[Fyorl]

Thanks for the feedback Kim, unfortunately I dont have the bandwidth to continue with this at the moment, @arbron would you mind finishing this off?

No problem, Max, thanks for your hard work on this. I can make these changes and get this merged.

[MaxPat931]

Awesome, thanks Kim, looking forward to it!