Placeholder Items - Shopkeepers/Shopkeepers-Wiki GitHub Wiki

When a player sets up a trade in one of their shopkeepers to buy items from other players, they usually need to own at least one of the items they want to buy more of. To alleviate this limitation, players can use renamed paper items as substitutes for items that they don't have.

A placeholder paper item can be created by renaming a normal paper item in an anvil: If the paper's name matches the name of a known item type, it is considered a 'placeholder item' by the shopkeeper and is immediately converted to the substituted item when used inside the shopkeeper editor.

If what appears to be a placeholder item is not converted, its name probably does not match a known item type. Valid item type names can for example be found here: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Material.html

• Only item names are supported. Block names for which there exists no equally named item (such as for example air, water, piston_head, bubble_column, etc.) will not work.
• Non-english item names, as well as some item display names that don't match their item type name, are not supported.
• The parsing is lenient to some extent:
  • The Minecraft namespace prefix (minecraft:) is optional. Some item type names are even too long to be used in anvils if the prefix is included.
  • The upper and lower case of characters is not important.
  • Leading and trailing whitespace is ignored.
  • Spaces and dashes are converted to underscores.
  • Any color codes are ignored.

Other interesting notes:

• Only the item type can be specified. Other properties of the substituted item are not supported.
• Placeholder items are supported by the selling, buying, and trading player shopkeepers. Admin shopkeepers treat them like normal items.
• Since the placeholder items are immediately replaced inside the editor, it is not possible to setup player shopkeeper trades that buy or sell the placeholder items themselves. But normal paper items, and paper items whose names do not match any valid item type, are treated like normal items and can be traded as usual.
• Placeholder items can not only be used for items that are bought, but also for items that are sold. This allows players to setup trades before they have the items required to fulfill these trades.

It is possible to specify basic enchanted books via placeholder items.

• The used naming format is <enchantment> <level>.
• The parsing is similar to that of item type names: The normalized item name has to match the id of the intended enchantment (see https://minecraft.wiki/w/Enchanting#Summary_of_enchantments).
• Aliases have been defined for some of the enchantments, so that for example curse of binding is correctly mapped to the enchantment with id binding_curse.
• Only a single enchantment can be specified.
• The enchantment level can be freely specified, even outside the range of enchantment levels that can usually be obtained in vanilla Minecraft.
  • Levels outside the range of shorts are truncated to the nearest valid short number.
  • If no level is specified, or if the level cannot be parsed, the enchantment's minimum level is used (usually 1).
  • Up to level ten, the level can also be specified via roman numerals (I to X).
  • It is also possible to specify the levels min or max, which results in the normal minimum or maximum level of the specified enchantment to be used.

It is also possible to specify basic potions, splash potions, lingering potions, and tipped arrows via placeholder items.

• The used naming formats are:
  • Potion: [long] [strong] [potion] [of] [long] [strong] <potion type> [2|ii] [potion] [2|ii]
  • Splash potion: [long] [strong] <splash> [potion] [of] [long] [strong] <potion type> [2|ii] <splash> [potion] [2|ii]
  • Lingering potion: [long] [strong] <lingering> [potion] [of] [long] [strong] <potion type> [2|ii] <lingering> [potion] [2|ii]
  • Tipped arrow: [long] [strong] [tipped] [potion] <arrow> [of] [long] [strong] <potion type> [2|ii] [tipped] [potion] <arrow> [2|ii]
• <potion type> has to match the name of a potion.
  • Similar as for item type and enchantment names, the parsing of the potion name is also lenient to some extent.
  • We support the potions that can be found in the creative inventory (see https://minecraft.wiki/w/Potion). Custom potion items with arbitrary effects and properties are not supported.
  • Bukkit's potion type names (https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/potion/PotionType.html) and some potion effect names (https://minecraft.wiki/w/Effect) may currently be recognized, but are not officially supported. They may be removed in the future. Try to stick to Minecraft's potion names. For example, use healing instead of instant heal or instant health.
• The keywords splash, lingering, and arrow are used to identify the different item types. If none of these keywords is found, a normal potion item is assumed.
• The keywords long, strong, 2, and ii specify long or strong variants of the specified potion. There are currently no potion variants that are both long and strong at the same time. Consequently, only one of these keywords is allowed to be used at the same time.
  However, we currently ignore any additional occurrences of the respectively other keywords. If the specified potion type does not support the selected variant, the keyword is currently ignored as well. But this might change and potentially become more strict in a future release.
• Each keyword can occur at most once, but there may be multiple valid locations at which it can occur (which is why the above formats mention some keywords multiple times).
  However, for simplicity, the parsing does not actually take the order or dependencies of words into account currently, but only checks for the presence of the various keywords. But this might change and potentially become more strict in a future release.
• Any other words in the above formats that were not mentioned as keywords are optional.