Skip to content

Tips & Tricks

To make your enchantments even better, there's support for placeholders in actions and conditions.

Many of these will be directly referenced in the built-ins section.

PlaceholderAPI

PlaceholderAPI is a plugin that's required for UnderscoreEnchants to run, as outlined in the setup guide. It provides a bunch of placeholders and a lot of plugins hook into it to add even more.

Example: %player_online% (1)

  1. Learn more about PlaceholderAPI here

The placeholders from PlaceholderAPI can be used in actions' and conditions' arguments.

Example: 

"action": "forward %player_food_level%"

UnderscoreEnchants placeholders

UnderscoreEnchants also provides placeholders. They have a different syntax. Take a look:

<target=first_player:placeholder=attribute:arguments={type=GENERIC_MOVEMENT_SPEED}>

UnderscoreEnchants' placeholders are enclosed in angle brackets. They can contain three fields: target, placeholder and arguments in any order. The fields must be separated by a colon (:).

target

Optional field

This field indicates whom to parse the placeholder against. Please refer to the target specification in the enchantments guide for more details. Beware that this field will default to the target specified for the action/condition that homes this placeholder in its arguments.

placeholder

Mandatory field

This is the placeholder itself with no arguments. Refer to the built-in placeholders page to see what placeholdersare bundled with the plugin, or/and install third-party plugins that hook into UnderscoreEnchants and add extra placeholders.

arguments

Optional field

This field is technically optional, because not all placeholders require arguments. However, if a placeholder does require arguments and you do not provide them, it will not be parsed correctly.

Arguments have the following syntax:

arguments={key=value|key=value|key=value}

To know which keys to use and which values are expected, you should take a look at the documentation of the specific placeholder you are using.

There's an additional placeholder in the format {amount_X}, where X is an enchantment level. It will be replaced with the amount of enchantments with this level that have been found.

Arithmetic expressions

Additionally, actions' and conditions' arguments support arithmetic expressions. They will be evaluated when evaluating the arguments. The library used for evaluating the expressions MathParser.org-mXparser; the syntax for all possible expressions can be found here.

Example: 6 + sin(15[deg])

Item format

The item format, whenever any condition/action expects an item (not an item type), is parsed as a component string. Additionally, you can use the following format, assuming ITEMs are correct component strings:

  • ITEM - returns ITEM
  • ITEM_1!ITEM_2 - returns either ITEM_1 or ITEM_2 (50% chance per each)
  • ITEM_1|40%!ITEM_2|60% - returns either ITEM_1 with a 40% chance or ITEM_2 with a 60% chance
  • ITEM_1|15%!ITEM_2|ITEM_3|50% - returns either ITEM_1 with a 15% chance, ITEM_2 with a (dynamically calculated) 35% chance, or ITEM_3 with a 50% chance
  • ITEM|70% - returns either ITEM with a 70% chance or nothing with a 30% chance
  • ITEM_1|50%!ITEM_2|30% - returns either ITEM_1 with a 50% chance, ITEM_2 with a 30% chance, or nothing with a 20% chance

The total chance must never exceed 100%.

Materials, entity types, etc.

Whenever an action/condition expects a material, entity type, sound, etc., these are the places to find them:

Materials

Sounds

Entity types

Effects

Particles

Slots

Sometimes the action/condition will require you to specify an item slot to find an item. In most cases, this is the expected syntax:

  • h for head item (helmet/skull/etc)
  • c for chest item (chestplate/elytra)
  • l for leggings
  • b for boots
  • m for main hand
  • o for off hand

You can use anything that starts with these letters case-insensitive (e.g. HELMET will be evaluated as h).

Comparison

Some conditions are based on comparison and require comparison operators as arguments. Here are all the available comparison operators:

  • =, ==, ===, is, equals, equal - verifies the equivalence
  • >, more, above, larger, morethan, largerthan - verifies that the current value is above the compared value
  • <, less, under, smaller, lessthan, smallerthan - verifies that the current value is under the compared value
  • >=, => - verifies that the current value is equal to or above the compared value
  • <=, =< - verifies that the current value is equal to or smaller the compared value