Creating enchantments
The main selling point of UnderscoreEnchants is the fact that it is trivial to create and modify custom enchantments. The system is very extensive and easy to figure out. This part of the guide touches specifically creating the .json files of the enchantments. The developer guide for working with the API also describes creating new registrables to use in enchantments.
Example
Take a look at an enchantment that combines almost everything there is to an enchantment:
{
"name": "Parkour",
"author": "Roughly_",
"description": [],
"chance": 70,
"trigger": "gothurt",
"applicables": ["feet"],
"enchantmentSeekers": ["feet"],
"activationIndicator": "bossbar",
"forbidden": ["leather_boots", "chainmail_boots"],
"conflictsWith": ["frost_walker", "depth_strider"],
"requiredEnchantments": [ { "key": "unbreaking", "seekers": ["feet"], "levels": "1-3,5" } ],
"requiredPlugins": [ { "name": "PlaceholderAPI", "displayName": "PlaceholderAPI (2.10.9+)", "link": "https://www.spigotmc.org/resources/placeholderapi.6245/" } ],
"conditions": [ { "condition": "cause falling" }, { "condition": "dmg > 3" } ],
"obtainmentRestrictions": [ { "type": "enchanting_table", "levels": "1-3,5" } ],
"levels": [
{
"level": 1,
"conditions": [ { "condition": "damage lethal", "negate": true } ],
"chance": 95,
"cooldown": 5,
"actions": [
{ "action": "time 10000 <target=first_player:placeholder=player_world>", "delay": 1, "chance": 50 },
{ "action": "player-set-hand MAIN DIAMOND", "target": "first" },
{ "action": "cancel" }
]
}
]
}
Fields specification
Below is the specification for every field. Before you create an enchantment, please get familiar with JSON. You can either just look at the example above to get a gist of what JSON looks like or take a look at this post on the StackOverflow blog.
name
Mandatory field
This field is used to identify the enchantment and to create a namespaced key to use internally. Two loaded enchantments cannot have the same name.
Example:
item
Optional field
This field indicates the item to show in the browsing GUI for this enchantment. It is mandatory if you plan on uploading the enchantment to a repository, but optional if you aren't. You can find the list of all items here.
Example:
description
Optional field
This field is used in browsing GUIs and when debugging the enchantment. Additionally, it's good to have a description for a complex enchantment to be able to easily later troubleshoot it if it is not working correctly.
Example:
author
trigger
Mandatory field
A trigger is what activates the enchantment. If this field is not present, or the specified trigger does not exist, the enchantment will not be registered.
Refer to the built-in triggers page to see what triggers are bundled with the plugin, or/and install third-party plugins that hook into UnderscoreEnchants and add extra triggers.
Example:
chance
Optional field
This field indicates the chance of activation as a percentage (defaults to 100.0).
Example:
cooldown
Optional field
This field indicates the cooldown of the enchantment in ticks (1 tick = 0.05 seconds). Please make sure to only set a global cooldown or a level cooldown, otherwise unexpected behavior might occur.
Example:
indicator
Mandatory field
An indicator is what tells the player that they have activated the enchantment. It can be a message, particles, actionbar, etc. If this field is not present or the activation indicator is not found in the registry, the enchantment will not be registered.
Refer to the built-in indicators page to see what indicators are bundled with the plugin, or/and install third-party plugins that hook into UnderscoreEnchants and add extra indicators.
Example:
applicables
Optional field
This field is a list of applicables to which the enchantment can be legally applied (via the enchantment table, anvil or the command). Note that, even though it is optional, if the field is not found or is empty, you will not be able to apply this enchantment to any item unless you set the bypass value to true in the /ue enchant command.
Refer to the built-in applicables page to see what applicables are bundled with the plugin, or/and install third-party plugins that hook into UnderscoreEnchants and add extra applicables.
Additionally, if you prefix the applicable by a pound sign (#), you can specify materials instead of applicables.
Example:
targetPlayer
Optional field
If you are working with PVP enchantments, by default the main player is the attacker. If you wish to instead send the activation indicator to the
victim, seek items on the victim, etc (for example, if you are working with an armor enchantment), you can use the field notifiedPlayer.
It can take two values (case-insensitive):
firstsecond
first is default behavior, so if you want to use it, you don't need to specify this field at all.
forbidden
Optional field
This field is a list of materials to which the enchantment can not be legally applied (via the enchantment table, anvil or the command). Please refer to the link above to fill this field.
Example:
seekers
Mandatory field
Seekers are used to find the enchanted items for a player. By default, the plugin does not know where to look for enchanted items. Thus, to allow both liberty for the enchantment creator and to concretize the location of items, enchantment seekers are used. This field requires a list of seekers.
Refer to the built-in seekers page to see what seekers are bundled with the plugin, or/and install third-party plugins that hook into UnderscoreEnchants and add extra seekers.
Example:
conflicts
Optional field
This field is a list of enchantment keys (without the namespace) with which this enchantment conflicts. For almost all vanilla and custom enchantments, the key is the name of the enchantment, lowercased, and spaces replaced with underscores (_).
Example:
unique
Optional field
This field is a true|false field. It indicates whether this enchantment can be the only one on an item (if an item has a unique enchantment, it cannot be enchanted any further; if an item has enchantments, it cannot be enchanted with a unique enchantment). Defaults to false.
Example:
stackable
Optional field
This field is a true|false field and is used to denote whether the effects of this enchantment are stackable. This means that if, for example, the player has two items enchanted with level 1 of this enchantment and one item with level 2 of this enchantment, the effects of level 1 will take place twice and the effects of level 2 will take place once. If is set to false, only the highest discovered level will be activated once. Defaults to false.
Example:
conditions
Conditions are complex JSON objects. For an enchantment to be activated, all the conditions must evaluate to true. This list is optional.
Here's an example of a condition in a list of conditions:
condition (conditions)
Mandatory field
This is the name of the condition and any arguments if necessary.
Refer to the built-in conditions page to see what conditions are bundled with the plugin, or/and install third-party plugins that hook into UnderscoreEnchants and add extra conditions.
Example for condition damage and argument lethal:
negate (conditions)
Optional field
This is a true|false field indicating whether to negate the result (e.g. if the condition evaluates to false, it will be changed to true). Defaults to false.
Example:
target (conditions)
Optional field
This field indicates what/whom to target when evaluating the condition. Defaults to first_player.
All values will be lowercased and stripped of dashes and underscores (e.g. First_Player will be evaluated as firstplayer). This field accepts values that start with:
secondp- indicatessecond playert- indicatesthird playere- indicatesentityb- indicatesblockfirsti- indicatesfirst itemsecondi- indicatessecond item- Everything else evaluates to
first player.
Example:
obtainmentRestrictions
Obtainment restrictions are complex JSON objects. They specify how the enchantment can NOT be obtained - this means everything that is specified in this list is off-limits. This list is optional.
Here's an example of an obtainment restriction in a list:
type (obtainment restrictions)
Mandatory field
This field indicates the type of obtainment that will be restricted.
Accepts values (case-insensitive): enchanting_table, trades, fishing, loot.
Example:
levels (obtainment restrictions)
Mandatory field
This field indicates the levels that will be restricted. The levels should be separated with commas (,); additionally, if there is a sequence of levels, they can be written as min-max. Example: 1-5,7,9-15 will restrict all levels from 1 to 5 inclusively, then level 7, and all levels from 9 to 15 inclusively.
Example:
requiredEnchantments
Required enchantments are complex JSON objects. They specify the enchantments that need to be present on an item to activate the enchantment. This list is optional.
Here's an example of a required enchantment in a list:
key (required enchantments)
Mandatory object
Please refer to conflicts' specification on keys.
seekers (required enchantments)
Mandatory object
Please refer to the seekers specification.
levels (required enchantments)
Mandatory object
Please refer to the obtainment restrictions' specification on levels.
requiredPlugins
Required plugins are complex JSON objects. They specify the plugins that need to be loaded for the enchantment to activate. This list is optional.
Here's an example of a required plugin in a list:
"requiredPlugins": [
{
"name": "PlaceholderAPI",
"displayName": "PlaceholderAPI (2.10.9+)",
"link": "https//www.spigotmc.org/resources/6245"
}
]
name (required plugins)
Mandatory field
This field denotes the name of the plugin. It should match the name exactly (the plugin's name in its plugin.yml), otherwise it will not be treated correctly.
Example:
displayName (required pluigins)
Optional field
This field denotes what the administrator will see in the browsing GUI. If not specified, will fallback to the name's value.
Example:
link (required plugins)
Mandatory field
This field denotes the link to the resource. The administrator will receive this link in chat when trying to download the plugins.
Example:
worldBlacklist
Optional field
This is a list of strings that contains all the worlds in which this enchantment can NOT be activated. If this field is present, all the worlds will work fine except for those specified here.
Example:
worldWhitelist
Optional field
This is a list of strings that contains all the worlds in which this enchantment can be activated. If this field is present, all the worlds will NOT work except for those specified here.
Example:
levels
This field is the core of the enchantment. It stores all of the levels of the enchantment along with their own cooldowns, actions, conditions, etc. It is mandatory to have at least 1 level.
Here's an example level in a list:
"levels": [{
"level": 1,
"conditions": [ { "condition": "damage lethal", "negate": true } ],
"chance": 95,
"cooldown": 5,
"actions": [
{ "action": "time 10000 <target=first_player:placeholder=player_world>", "delayTicks": 1, "chance": 50 },
{ "action": "player-set-hand MAIN DIAMOND", "player": "first" }
]
}]
level (levels)
Mandatory field
This field indicates the level index. There cannot be two levels with the same index in one enchantment.
Example:
conditions (levels)
Optional field
Please refer to the conditions specification.
chance (levels)
Optional field
Please refer to the chance specification.
cooldown (levels)
Optional field
Please refer to the cooldown specification. Additionally, please make sure to only set a global cooldown or a level cooldown, otherwise unexpected behavior might occur.
actions
Actions are complex JSON objects. They are only present inside of levels (a top-level actions object will not be recognized). It is mandatory to have actions for every level.
There are two ways to specify actions: actions with no shared behavior and actions with shared behavior. Here are the examples for both:
"actions": [
{
"delay": 1,
"action": "time 10000 world"
},
{
"chance": 20,
"action": "heal"
}
]
"actions": [
{
"delay": 1,
"actions": [ "time 10000 world", "action": "heal" ]
}
]
The difference between the two is that for actions with shared behavior, all the actions inside the actions list will be affected by the other extra behavior (chance, etc), while actions with no shared behavior, consequently, behave on their own.
delay (actions)
Optional field
This field indicates the delay in ticks before the action is executed (1 tick = 0.05 seconds).
Example:
chance (actions)
Optional field
Please refer to the chance specification.
target (actions)
Optional field
Please refer to the conditions' specification on the target field.
conditions (actions)
Optional field
Actions can have their own conditions. Please refer to the conditions specification.
action/actions (actions)
Mandatory field
For any action object, there can either be one single action (a string) or one single actions (a list of strings).
Refer to the built-in actions page to see what actions are bundled with the plugin, or/and install third-party plugins that hook into UnderscoreEnchants and add extra actions.
An action string consists of the action name and arguments if necessary; an actions list of strings is identical, but contains multiple strings instead of one.
Example:
What next?
Please make sure to visit the tips & tricks page to enhance your enchantments even further.