Idea 1: Support for automatic withdrawning and conversion of vault money to currency items

Reference: https://dev.bukkit.org/projects/shopkeepers?comment=3404

Idea: When a player opens a trading interface and the selected trade requires the currency items, the plugin would automatically withdraw up to two stacks of the player's vault balance and automatically insert it into the trading input slots (if those are currently empty).
When the player trades, those two stacks would get refilled by further withdrawning from the players account.
When the player switches to a trade that does not require the currency items, the plugin would automatically deposit the remaining currency items from the trading input slots back into the vault account again.
When the player manually picks up the currency items from the input slots, options could be to either ignore it, or to either react (might be complicated to detect) or to periodically check and then refill the input slots again by further withdrawing.

New required settings would be the mapping between vault money and the currency items (how much vault money corresponds to one currency item). And a setting to enable/disable this feature.
If the trade requires high currency items in one or both input slots, the inserted items would be converted to high currency items accordingly and withdrawing/depositing happen as needed.

---

Another alternative to support virtual Vault currency in shopkeeper trades is to introduce a type of item that represents a certain amount of the Vault currency. There are a few aspects to consider.

How is the money item defined?

• Define it inside the shopkeepers config.
  • But: Servers might already use some other plugin to represent money as items. For example, some plugin might deeply integrate its money item into Minecraft mechanics such as crafting, mob drops, looting, etc. Replicating these integrations is not a goal of the Shopkeepers plugin. For those servers there might therefore be the interest to re-use these third-party items in the context of Shopkeepers.
    However, a primary goal of ours is to not introduce any plugin dependencies, or having to account for plugin-specific ways in which the value of money items is represented. Not sure if this can be achived..
    • One option could be to require these externally defined money items to contain some Shopkeepers specific metadata for identifying the money value. But:
      • This would not work with plugins that don't allow configuring their money items.
      • This would not work for already distributed items.
    • Another option could be to investigate how the most common other plugins represent their money values and then offer configuration options to account for those. E.g. define specific metadata keys inside the config that can be used to look up the money value of some item.
      • This might be quite limiting.
      • For this to be useful, we would need to account for new third-party plugins once the define new ways in which they represent their money value. This is exactly what we are trying to avoid in the first place.
    • Offer explicit integrations for individual money item plugins. The goal is to avoid this.
  • There might be the need to define multiple different money items. E.g. to represent different currencies, or values, for cosmetic purposes, for backwards compatibility reasons (when making changes to the defined money item), etc.
• Another option is to allow the use of arbitrary items as money item and, instead of having them pre-configured inside the config, identify them based on metadata.
  • A command could be offered that adds the respective metadata to an item. This metadata could contain the value, as well as an (optional) currency (if the server defines multiple currencies). (However, the VaultAPI does not actually support multiple currencies ..)

How do players get the money item?

• One possibility could be to offer a command to withdraw/deposit Vault money for this money item.
  • However, I would prefer to not require players to use commands for this.
    • Depositing could even work more automatically (avoiding the command) by:
      • Interacting with the item in hand to deposit the money.
      • Let the shopkeeper automatically deposit the money when one of these items is traded (either sold or bought).
      • We could offer both means by differentiating between money items that are automatically deposited, vs money items that are more physical and require and explicit interaction by the player in order to be deposited.
  • Also, there already exist plugins that represent vault money via items, and that offer means to convert between items and vault balance. Real benefit is only achieved if some parts of the process (converting Vault balance to money items, sell or receive money items in trades, convert money items to vault balance) are automated in the shopkeeper context. E.g:
    • Dynamically withdrawing/depositing between items and vault balance within the shopkeeper trading interface (as suggested by this ticket).
      • However, this would universally affect all trades that accept currency items, which might not be intended in some cases. In some cases, the goal might be to trade the currency items like any other normal item.
    • Automatically withdrawing/depositing money from/to the vault balance when certain items are used in shopkeeper trades. With this there would be some control over which trades apply this additional withdrawing/depositing behavior. But there would still be the question how these items are created and distributed to players in the first place.
• A special type of admin shopkeeper could be introduced to sell these money items. E.g. exchange a normal paper item for a paper money item, and the shopkeeper automatically withdraws the respective amount of money from the trading player's balance. This has also been suggested here: https://www.spigotmc.org/threads/shopkeepers.447969/page-8#post-4330239
  • However, I would prefer to not have these input item (e.g. paper) fixed, or even configured inside the config. Instead, setting up arbitrary trades for these money items should be possible to do in-game.
  • And even for the money item it make sense to not require these to be pre-configured (see above).
• It might be possible to use regular admin shopkeepers to sell these money items. The only requirement would be that when a player buys the item, their vault balance is reduced by the corresponding amount. And the trade does not work if the player does not have the required balance.
  • However, this logic would need to be limited to admin shopkeepers: When such a money item is sold by a player shop, it makes no sense to deduct the money amount from the trading player's balance.
  • Actually, there might very well be cases in which an admin shop is supposed to give out vault balance / the money item. I.e. cases in which is should not withdraw money from the player but behave as a 'normal' money item.
    • One option could be to have a flag inside the money item's metadata whether it should withdraw the amount from the player buying the item. But this seems unnecessarily complex.
• Another option could be to allow players to create these 'money placeholder items' similar to how they can create placeholder items: By renaming a certain type of item (e.g. paper) in an anvil, e.g. to "100$" (or some other pattern defined inside the config).
  • Players/admins could then set up trades that use these money placeholder items, both as inputs or as outputs.
    • When one of these items is traded as input, the trading player's balance is reduced by the amount and the shop owner's balance is increased.
    • When one of these items is traded as result item, the transfer of money is in the opposite direction.
    • When trading with an admin shopkeeper, the shop owner's part of the transfer is skipped.
  • However, players that want to buy something would need to manually create these placeholder items themselves, to be able to use them inside the trade. Having shop owners need to be aware of this niche feature to set up trades that involve receiving or giving money is fine, but having all players need to be aware of these items and how they are created in order to use these trades might cause confusion.
    • Maybe automatically insert respective placeholder items into the trading inputs?
      • Might introduce possibilities for possible duplication issues with these items.
    • Offer some other, more user-friendly way to distribute these items to players. This is a similar problem to the initial one, but now involves these money placeholder items instead of money items..
      • Admins could set up an admin shop to sell them.
      • There could be a command to generate them.
        • Requires a command ...
        • Since these placeholder items are supposed to be very cheap / for free (they don't represent actual money until they are used inside a trade), this can be abused for item duplications.
• It is already possible to use any other normal non-item based shop plugin out there to buy/sell some 'money item' for actual Vault money. I.e. instead of having a dedicated shopkeeper type for buying/selling money items to convert between vault money and item representations, one can already use any shop plugin out there to implement this conversion.

There might be the need to restrict how these money items are used. E.g. block them from being used in crafting, etc. But catching (and maintaining) all cases in which items can usually be used in vanilla Minecraft is cumbersome and prone to errors.

• One option is to not even try to prevent their normal usage and let players take care of not accidentally using their money items in crafting etc. / require the server admins to ensure that their chosen money item(s) cannot be used for anything else. Similar to how it is already the case for the configured currency items: It is up to the server admins to pick a currency item and ensure that this item can only be used in the ways intended by them.
• Another option is to restrict the money item to a specific type of item, such as paper, that has very limited and known ways of being used in Minecraft. But this might be too restrictive: Some servers might want to use their own types of items (e.g. a head item representing a bag of gold, emeralds/diamonds/gold/..., etc.).

Money items that withdraw/deposit money when they are interacted with could already be created via command items that execute respective withdraw/deposit commands.

• They would also need to remove the item.
• It might also be possible to trigger these command items automatically when the item is traded.
• But: These money command items would need to be actual money items that withdraw money when they are created, and can always deposit money when they are used. I.e. they cannot be 'cheap placeholders', because we cannot check if the commands are able to succeed and then conditionally abort the trade, for example if one party does not have enough balance.

More on command items integrated into Shopkeepers (TODO move this into a separate ticket):

• To avoid abuse by having players/the server execute arbitrary commands, creating these items would need to be limited to server admins. But: Server admins could create money items with respective commands, and then sell those via an admin shop to players, so that they can use them inside their own player shops.
  • But: How to sell these money items for vault money instead of other items? This is part of the original problem.
• It might make sense to have command items that nee to be interacted with versus command items that are triggered automatically when being traded.
• There are already command item plugins out there with quite sophisticated features, such as delays, conditional executions, etc. It is not a goal to offer a equally sophisticated set of features.
  • One option could be to not add command items to the Shopkeepers plugin directly, but instead provide an extension that integrates with some other command item plugin to triggers its commands when one of these items is traded.