# 🎉Welcome

## Links

### Get the plugin

* **SpigotMC:** [FREE](https://www.spigotmc.org/resources/mythicchanger-auto-match-change-drag-change-gui-change-in-1-plugin-1-14-1-21-10.98523/) | [PREMIUM](https://www.spigotmc.org/resources/ultimateshop-premium-be-je-menus-rewards-shop-daily-shop-item-in-1-plugin-1-14-1-21-10.113069/) (will post each update)
* **Polymart:** [FREE](https://polymart.org/product/4296/ultimateshop) | [PREMIUM](https://polymart.org/product/5757/mythicchanger-premium) (will post each update)
* **BuiltByBit:** [PREMIUM](https://builtbybit.com/resources/mythicchanger.41836/) (will post each update)
* **Modrinth:** [FREE](https://modrinth.com/plugin/mythicchanger) (weekly update, maybe not latest version)

### Get support <a href="#get-support" id="get-support"></a>

* All users have an obligation to comply with our rules after joining the Discord server, which can be viewed in the rules channel. If you do not agree with our rules, you will not be able to receive our service support. Users who violate the rules will be punished according to the situation, including permanent ban.
* Every user is obligated to comply with our plugin terms of use. You can find these in the **LICENSE** file within the JAR file. We do not provide any assistance to users who fail to comply with the terms of use.
* Compared to users who have purchased the paid version, our service support priority for free users will be lower, with more requirements and restrictions. I have invested a lot of time and effort in developing plugins, but despite this, I have provided a free version and the complete plugin source code. I have not closed the source or restricted the number of user IP addresses used. Therefore, better service support is not free, and you should not ask me to provide good service for free. If you want your issue to be taken seriously, please consider purchasing a paid version to support plugin development.
* Support is only available at our [Discord](https://discord.gg/rzajeybhbw) server.
* 因 Discord 在中国大陆区域不可用，如果您在中国大陆购买了此插件，可以凭购买的账号平台、名称，在此QQ群享受售后服务：815351827。

## Info

* Built-in 45 item change rule, including display name, lore, custom model data, enchantments and replace the whole item, and even randomly replace item, etc...
* Built-in 21 match rule, including display name, lore, 10+ hook plugins like ItemsAdder, MMOItems, EcoItems, saved items, vanilla items, NBT match, material tag, material type and so on!
* You create create new custom change or match rule which by using our API.
* Built-in Item Format which allow you make any item you desire, including custom food, custom tool, custom attribute, custom armor, and so on.
* Including fake change and real change. Fake change is display virtually, and it only change in client side. Real change is change both in client and server side.
  * For example, if you are using remove\_enchants change rule, if you set this rule in fake changes, item just display it don't have this enchantment, but actually it has and the enchantment will also take effect.
  * If you set it in real change, then the enchantment will actually gone. No one will find it anymore.
* Support Hex Color and Gradient Color in anywhere.
* Support use Powerful Item Placeholder in change rule's config and item lore. You can easily display anything in item lore, or set new value based on item in configs! By this feature, we also allow you use PlaceholderAPI placeholder in item lore.
* 3 Different change types!
  * Auto Match & Change: Plugin will auto match the item you set and auto change them.
  * Drag Change: Drag Apply Item onto the item you want to change, then all is done!
  * GUI Change: Open a GUI and drag both Apply Item and the item you want to change in it, then click the confirm button, that's all!
* Built-in Poweful Actions and Conditions system, allows you set conditons to active the change and the actions will execute after change the item. (Premium)
* Each item can use unlimited apply item type. You can easily make MythicChanger be a gem plugin by use our Drag Change or GUI Change feature.
* Built-in simply item manager feature, you can easily save your hold item and use command to give saved item to players! Also provide a command to help you view the NBT data of the hold item. (Premium)
* Auto hook into InteractiveChat, TrChat, QuickShop-Hikari to help you display fake change item in chat! (Premium)
* Standard Localized Item Name Translate.
  * Due to the fact that the Minecraft server does not store client language files, the plugin cannot know the name of the item you hold displayed on your client. Therefore, in most scenarios where the item name is displayed, we directly display its English name. Now this new feature will automatically download the client language file and translate your item name when you use change rule and item placeholder.


# ✅Requirements

## Java Version

* Basic Requirement: **Java16+**
* **Java 17+** is <mark style="color:red;">recommended</mark>. Java17 and above versions are recommended, but plugins are compiled using **Java16**, so theoretically, you only need Java16 or higher versions.

## Server Software

| Server          | Can work in your server                                                                                                   | Can get offical support                                                                                                                                                                          |
| --------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Spigot          | <p>✅<br>Some features does not provide in Spigot servers</p>                                                              | ✅                                                                                                                                                                                                |
| Paper/Purpur    | <p>✅<br>Can provide subtle performance improvements.</p>                                                                  | ✅                                                                                                                                                                                                |
| Folia           | <p>❓<br>Any problems only occurs in Folia servers may not be solved. Plugin is not designed for multi thread support.</p> | <p>❓</p><p>Folia's support is in the <mark style="color:red;">early testing stage</mark> and may be released in official versions or removed in the future. This support is not a guarantee.</p> |
| Other softwares | ❌                                                                                                                         | ❌                                                                                                                                                                                                |

## Plugin Requirements

* For version below 2.4.0: Latest **dev** version of **ProtolcolLib** is <mark style="color:red;">**required**</mark>. Plugin won't work without this plugin.
* For version 2.4.0+: Require **packetevents**!

## Server Version

| Version              | Can work in your server                                                                                                   | Can ger offical support |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| **Below 1.14**       | ❌                                                                                                                         | ❌                       |
| **1.14 \~ 1.20.4**   | <p>❓<br>The plugin can run on these versions, however, any issues caused on these versions will not be resolved.</p>      | ❌                       |
| **1.20.5 and above** | <p>✅<br>Using versions <strong>1.21.5</strong> and above is the most recommended, as you can enjoy the best features.</p> | ✅                       |

* If you encounter errors while using a certain version, <mark style="color:red;">please join our Discord feedback</mark>.


# ⚙️Install

## Install <a href="#install" id="install"></a>

* Put the `.jar` file into your server's `plugins` folder.
* Stop your server and then restart it. <mark style="color:red;">Cannot load plugins in any other way while the server is starting</mark>.
* When updating plugins, please be sure to remove old versions.
* Previously, you used the free version, but now to upgrade to the paid version, you only need to install the paid version on the server and remove the free version. The configuration file of the plugin does not require any changes.
* When downgrading from **a new game version** to **an old version** on the server where the plugin is located, it is important to remove the `items` folder from the configuration file.
* When using the [Localized Item Name](/features/localized-item-name-premium) feature, it is important to note that when switching server game versions, the previously generated localized files need to be deleted.
* If you just want to use our match item feature without any need of change item, you can disable `packet-listener` option at `config.yml` file to improve plugin performance and disable auto item change feature.


# ⛔Limitation

## Creative Mode

The **fake change feature** of this plugin will not have any effect on **creative modes**.

## Compatibility of other packet based item plugins

Some other item plugins and enchantment plugins **MAY** are also using packet to change items, in which case MythicChanger's **fake change** may not work on items from these plugins. MythicChanger provides a free version for testing plugin compatibility.

## Real change is not instantaneous

This plugin does not instantly apply **real changes**. We will only attempt to make real changes to the item after the player interacts with it. In survival mode, the vast majority of operations that can obtain items will be recognized by the plugin and successfully perform real changes. So this limitation can almost be ignored.

## Real change will only occur within the player's inventory

In order to prevent abnormal situations such as **item duplication**, **real change** will only be performed within the player's inventory, and items in the "treasure chest" and "vault" will not undergo real change. Due to this issue, it is highly recommended that you use both real change and fake change if you are using change rules like `replace-item`.

```yaml
fake-changes:
  replace-item:
    hook-plugin: MMOItems
    hook-item: 'MATERIAL;;REAR_INGOT'
real-changes:
  replace-item:
    hook-plugin: MMOItems
    hook-item: 'MATERIAL;;REAR_INGOT'
```


# 🔗Compatibility

This plugin mainly adds **direct compatibility** for some item plugins. If the item plugin you are using is not in the list, you can also use **indirect compatibility**.

## **Direct compatibility**

Directly compatible item plugins can **match these items** directly with **item ID**s from these plugins, or use items from these plugins in [ItemFormat](https://ultimateshop.superiormc.cn/format/itemformat-tm).

* ItemsAdder
* Oraxen
* EcoItems
* EcoArmor
* MMOItems
* MythicMobs
* eco
* NeigeItems
* ExecutableItems
* Nexo
* CraftEngine

## Indirect compatibility

If you want to use items from other plugins in [ItemFormat](https://ultimateshop.superiormc.cn/format/itemformat-tm) and this plugin is not directly compatible, you can save the item through the **save item** feature and then use it through the `material` option in **ItemFormat**. For **match items**, it is even simpler, and you can flexibly use other match rules to match this item, such as `contains-lore`, etc.


# 🛠️Configuration files

The plugin generates the following configuration files, some of which will only be generated after you first use this feature.

* `items`: Saved item files. You can add ItemFormat YAML files here; reload with `/mc reload` and give an item with `/mc givesaveitem <ID>`.
* `languages`: The location for storing language files. You can set the language file used by the plugin through the `config-files.language` option in the `config.yml` file. You can customize various messages within the plugin game through language files. It is not supported to display the corresponding language file based on the player client language. You can only display the same language for all players.
* `rules`: The location for storing **Auto Match & Change** feature's configuration files.
* `apply_items`: The location for storing **Apply Item** configuration files. **Drag Change / GUI Change** feature requires you consume Apply Item to apply item change onto specifed items.
* `config.yml` file: The location for main common settings for plugins.
* `generated-item-format.yml` file: When using the `/mc generateitemformat` command, we will parse the item you are holding into an **ItemFormat** and store the parsed **ItemFormat** content in this file.
* `XX_xx.json` file: Localized files automatically generated through [Localized Item Name](/features/localized-item-name-premium) feature. The name of this file is determined based on the localized language you have set for this feature, but it usually ends in `. json`.

Use `debuild-item-method: COMPONENT` to save supported Paper components on Paper 1.21.5+ with MythicChanger Premium. See [Component Format](https://github.com/ManyouTeam/MythicChanger/tree/master/docs/format/component-format.md) and [Testing Paper Components](https://github.com/ManyouTeam/MythicChanger/tree/master/docs/format/component-testing.md).

## Config.yml file content

It is recommend that you view this file at GitHub, becuase Wiki's `config.yml` maybe not **latest**. Click [here](https://github.com/ManyouTeam/MythicChanger/blob/master/src/main/resources/config.yml) to view this file on **Github.**

```yaml
# MythicChanger by @PQguanfang
#
# Read the Wiki here: https://mythicchanger.superiormc.cn/

# Some options require restart the server to make effect.

debug: false

# If you just want to use our match item feature without any need of change item,
# you can disable this option to improve plugin performance and disable auto item change feature.
packet-listener: true

# packetevents Support value:
#    LOWEST(0),
#    LOW(1),
#    NORMAL(2),
#    HIGH(3),
#    HIGHEST(4),
#    MONITOR(5)
# The value after the value just a number help you know it's level, do not type them in option.
packet-listener-priority: LOWEST

config-files:
  language: en_US
  # Premium version only.
  per-player-language: true
  force-parse-mini-message: true
  # Premium version only.
  minecraft-locate-file:
    # After enable, we will autoload Minecraft locate file when we need know an item's locate name.
    # It will make server little lag when loading this file because this file is very large.
    enabled: true
    generate-new-one: false
    file: 'zh_cn.json'

debuild-item-method: 'LEGACY'

# Support value: DEFAULT or ITEMBRIDGE
hook-item-method: 'DEFAULT'

# Premium version only.
math:
  enabled: true
  scale: 2

real-change-trigger:
  SetSlotPacket:
    enabled: true
  # Require Paper.
  # A better choice to replace "SetSlotPacket"
  PlayerInventorySlotChangeEvent:
    enabled: false
  InventoryClickEvent:
    enabled: true

fake-change-trigger:
  # Normal triggers like SetSlotsPacket, WindowsItemPackets, SetCursorItemPacket so on are force enabled.
  # Entity Packets means we will also modify item from other entities which is very cost server performance if you enable the two options here.
  EntityEquipmentPacket:
    enabled: false
  EntityMetadataPacket:
    enabled: false

ignore-warning: false

# Whether we keep item name to original in anvil name.
keep-name-in-anvil: true

# Whether only-in-player-inventory option in each rule only checks chest UI.
check-chests-only: true

ignore-player-crafting-slot: false

# Premium version only.
change-gui:
  title: '{lang:change_gui.title}'
  size: 27
  ignore-click-outside: false
  anti-dupe-checker: false
  item-slot: 11
  book-slot: 15
  confirm-slot: 22

  confirm-item:
    material: ANVIL
    name: '{lang:change_gui.confirm.name}'
    lore:
      - '{lang:change_gui.confirm.lore}'

  custom-item:
    2:
      material: PAPER
      name: '{lang:change_gui.custom.item}'
    6:
      material: BOOK
      name: '{lang:change_gui.custom.book}'

  close-if-fail: true

# MY_CUSTOM:
#   title: 'Change your item!'
#   size: 27
#   item-slot: 11
#   book-slot: 15
#   confirm-slot: 22
#   confirm-item:
#     material: ANVIL
#     name: '&eConfirm'
#     lore:
#       - '&7Click to confirm change the item!'
#   custom-item:
#     2:
#       material: PAPER
#       name: '&bDrag the item you want change below.'
#     6:
#       material: BOOK
#       name: '&bDrag the apply item below.'
#   close-if-fail: true

apply-item-mode:
  drag-enabled: true
  # GUI mode is in EARLY ALPHA TEST, be careful to use!
  # Premium version only.
  gui-enabled: true

default-apply-item-limit: 1
```


# ⌨️Commands

## /mc generateitemformat

Save the item held in your main hand to `plugins/MythicChanger/generated-item-format.yml`. Each use overwrites that file. Set `debuild-item-method: COMPONENT` to use the component writer on Paper 1.21.5+ with MythicChanger Premium. See [Testing Paper Components](https://github.com/ManyouTeam/MythicChanger/tree/master/docs/format/component-testing.md) for a save/rebuild walkthrough.

Require `mythicchanger.generateitemformat` permission.

## /mc giveapplyitem \<itemID> \<playerID> \<amount>

Give [Apply item](/drag-gui-change/apply-item) to players.

Require `mythicchanger.giveapplyitem` permission.

## /mc help

View plugin help.

## /mc reload

Reload the plugin. Some changes still need restart the whole server.

Require `mythicchanger.reload` permission.

## /mc saveitem \<itemID> \[bukkit|itemformat]

Save your held item. `bukkit` is the default save method; `itemformat` follows `debuild-item-method`. For example, `/mc saveitem component-test itemformat` saves the ItemFormat under `items/component-test.yml`.

Require `mythicchanger.saveitem` permission.

## /mc givesaveitem \<itemID> \[player] \[amount]

Give saved item to players.

Require `mythicchanger.givesaveitem` permission.

## /mc viewnbt <mark style="color:red;">**(Premium version only)**</mark>

View hold item NBT info, it will only display the plugin supported NBT Type.

Require NBTAPI plugin.

Require `mythicchanger.viewnbt` permission.

## /mc openchangegui <mark style="color:red;">**(Premium version only)**</mark>

Open mythic change GUI, require you enable `apply-item-mode.gui-enabled` to **true** in `config.yml`. (This option require server restart)

Require `mythicchanger.openchangegui` permission.

## /mc openchangegui \<customModeName> <mark style="color:red;">**(Premium version only)**</mark>

If you have set a custom apply item mode for certain apply items, then players must use this command to enter the GUI where they can use this apply item.

Require `mythicchanger.openchangegui` permission and `mythicchanger.openchangegui.<customModeName>` permission.

## /mc setlimit \<amount> <mark style="color:red;">**(Premium version only)**</mark>

Set hold item's apply limit.

Require `mythicchanger.setlimit` permission.


# ❓FAQ

## Seems that my rule configs are correct, why my items does not change?

* MythicChanger won't modify creative mode players item, you have to change your game mode to survival or adventure.
* For real change: The modification is not immediate and requires players to interact with the item, such as droping it to the ground and picking it up again.
* Maybe your ProtolcolLib plugin is not correctly loaded or it is not latest (download latest at it's Jenkins!).

## Seems that when I click the item, it will disappear or dupe.

* Update MythicChanger to 1.3.2 and higher version maybe solve your problem.
* Try disable `real-change-trigger.InventoryClickEvent.enabled` option in `config.yml` then restart the server.

## Why I can not click a item?

* That maybe because you use `replace-item` change rule, and after replace the item, the new item still meet the match rule, so this has fallen into a dead cycle.

## This plugin crashs my server!

* This is likely due to your item replacement getting stuck in a dead loop. If the replaced item still meets the conditions of other rules, it will be continuously replaced. Please ensure that the replaced item will not meet any other rules.


# 🆚Compare

|                                                                                                                                                                                                                                                                                                    | Free | Premium |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | ------- |
| <p><strong>More Commands</strong> <br>Some commands are only available for premium version. For more info, please view <a href="/info/commands">Commands</a> page.</p>                                                                                                                             | ❌    | ✅       |
| <p><strong>GUI Change</strong><br>Premium version allows you use <strong>apply item</strong> in a GUI instead of drag and apply. For more info, please view <a href="/drag-gui-change/info-of-drag-gui-change">Info of Drag/GUI Change</a> page.</p>                                               | ❌    | ✅       |
| <p><strong>More Change & Match Rules</strong><br>Premium vesion can enjoy more change & match rules, we will continue to add new rules with free version will no longer get any new rules added.</p>                                                                                               | ❌    | ✅       |
| <p><strong>Condition Not Meet Action</strong><br><strong>Match Item Not Match Action</strong></p>                                                                                                                                                                                                  | ❌    | ✅       |
| <p><strong>Real Change Action</strong><br>Premium version allows you execute actions when apply real change for items. For more info, please view <a href="/auto-match-and-change/rule">Rules</a> page.</p>                                                                                        | ❌    | ✅       |
| <p><strong>Rule Change Condition</strong><br>Premium version allows set condition for Auto Match & Change rules. For more info, please view <a href="/auto-match-and-change/rule">Rules</a> page.</p>                                                                                              | ❌    | ✅       |
| <p><strong>More Powerful Item Placeholders</strong><br>Premium version can use more powerful item placeholders, some of them can even get item's NBT or Item Format value easily! For more info, please view <a href="/features/powerful-item-placeholders">Poweful Item Placeholder</a> page.</p> | ❌    | ✅       |
| <p><strong>Unlimited Apply Item</strong><br>You can create unlimited apply item with premium version. Free version can only create up to 3 apply items.</p>                                                                                                                                        | ❌    | ✅       |
| <p><strong>Localized Item Name</strong> <br>Premium version supports display item localized name for item without custom name. For more info, please view <a href="/features/localized-item-name-premium">Localized Item Name</a> page.</p>                                                        | ❌    | ✅       |
| <p><strong>Math</strong><br>Premium vesrion can freely use mathematical formulas and placeholders in some places. For example of this, please view <a href="/drag-gui-change/apply-item-example-attribute-scroll">this page</a>.</p>                                                               | ❌    | ✅       |
| <p><strong>More...</strong> <br>Many small differences were not mentioned here or, I forgot them put here, and more features that are only available in the paid version will be added in the future!</p>                                                                                          | ❌    | ✅       |


# 📝ItemFormat™

MythicChanger uses the same ItemFormat component keys as UltimateShop. Keep `material` and `amount` at the root, and put Paper component options under `component`.

```yaml
material: DIAMOND_SWORD
amount: 1

component:
  name: '<aqua>Component sword'
  glow: true
  damage: 25
  max-damage: 2048
```

Paper components require Paper 1.21.5+ and MythicChanger Premium. Newer components require the server version shown in each component heading.

* [Component Format](https://github.com/ManyouTeam/MythicChanger/tree/master/docs/format/component-format.md): each supported component, its configuration and minimum Paper version.
* [Testing Paper Components](https://github.com/ManyouTeam/MythicChanger/tree/master/docs/format/component-testing.md): version-specific ItemFormat examples and save/rebuild checks using MythicChanger commands.

Set `debuild-item-method: COMPONENT` in `config.yml` to save supported item properties inside `component` with `/mc generateitemformat` or `/mc saveitem <ID> itemformat`. This setting controls saving; it is not required to build an ItemFormat that already contains a `component` section.

Custom ItemFormat files go in `plugins/MythicChanger/items/`. Reload with `/mc reload`, then give an item with `/mc givesaveitem <ID>`. The ID is the file name without `.yml`.


# Component Format

Paper components are configured inside the `component` section of an [ItemFormat](/format/itemformat-tm). This feature requires **Paper 1.21.5 or later** and **MythicChanger Premium**. Components introduced in newer Minecraft versions require the corresponding server version.

Keep `material` and `amount` at the ItemFormat root. Put Paper component options under `component`:

```yaml
material: DIAMOND_SWORD
amount: 1

component:
  name: '<aqua>Component sword'
  lore:
    - '<gray>Built with Paper components'
  glow: true
  damage: 25
  max-damage: 2048
```

Component options are applied after the root ItemFormat options. When both configure the same property, the component value is applied last. `debuild-item-method` controls how items are **saved to ItemFormat**; you do not need to change it to build an item from a `component` section.

Use numbers and booleans as YAML numbers and booleans, without quotes. Use lowercase namespaced registry IDs such as `minecraft:sharpness` and `minecraft:attack_damage`. Enum values such as `EPIC`, `EAT` and `ADD_NUMBER` use the spelling shown in the examples.

## Server version support

| Minimum Paper version | Components and options                                                                                                |
| --------------------- | --------------------------------------------------------------------------------------------------------------------- |
| 1.21.5                | Base components documented below, including food, tools, equipment, consumables, damage resistance and blocking       |
| 1.21.6                | Attribute display modes; `equippable.can-be-sheared` and `equippable.shear-sound`                                     |
| 1.21.11               | Attack range, damage type, kinetic weapons, minimum attack charge, piercing weapons, swing animation and use effects  |
| 26.1                  | Damage resistance and blocking also accept lists of damage type IDs                                                   |
| 26.2                  | Sulfur cube content                                                                                                   |
| 26.3                  | Attack/interact animations, waxed signs, cushion color, villager food, pottery patterns, mob visibility and sign text |

Options for an unregistered component are not a compatibility fallback: they will not be applied on an older server. Use the examples for your server version. For a practical checklist and complete sample items, see [Testing Paper Components](/format/itemformat-tm/component-testing).

The version suffix on each component heading is the minimum Paper version supported by the plugin's component adapter. Options added later have their own version heading.

## Custom Name - 1.21.5+

Configuration key: `component.name`.

Sets the custom display name. MiniMessage formatting is supported.

```yaml
component:
  name: <aqua>Paper component name test
```

## Item Name - 1.21.5+

Configuration key: `component.item-name`.

Sets the item name component independently of the custom display name.

```yaml
component:
  item-name: <gold>Paper component item name
```

## Lore - 1.21.5+

Configuration key: `component.lore`.

Sets the lore lines in their configured order. MiniMessage formatting is supported.

```yaml
component:
  lore:
    - <gray>First lore line
    - <green>Second lore line
```

## Custom Model Data - 1.21.5+

Configuration key: `component.custom-model-data`.

Each type is a separate list. `float` entries must be numbers and `flag` entries must be booleans. Values should remain in the same order and should not multiply when the item is saved and rebuilt.

```yaml
component:
  custom-model-data:
    float:
      - 101.0
      - 202.5
    flag:
      - true
      - false
    string:
      - test-a
      - test-b
    color:
      - '#FF5555'
      - '#55FF55'
```

Custom model data does not create a model. A resource pack must define how these values change the item's appearance.

## Max Stack Size - 1.21.5+

Configuration key: `component.max-stack`.

Accepts 1–99. Use a stack size of 1 for damageable items.

```yaml
component:
  max-stack: 16
```

## Damage - 1.21.5+

Configuration key: `component.damage`.

Sets the amount of durability already used. Use a non-negative integer; this is not the remaining durability.

```yaml
component:
  damage: 37
```

## Max Damage - 1.21.5+

Configuration key: `component.max-damage`.

Sets the maximum durability to a positive integer. Use `max-stack: 1` for a damageable item.

```yaml
component:
  max-damage: 2048
```

## Enchantment Glint - 1.21.5+

Configuration key: `component.glow`.

Overrides the enchantment glint. Use `true` to show it or `false` to hide it.

```yaml
component:
  glow: true
```

## Unbreakable - 1.21.5+

Configuration key: `component.unbreakable`.

Use `true` to prevent normal durability loss. Omit this option when testing durability loss and item breakage.

```yaml
component:
  unbreakable: true
```

## Rarity - 1.21.5+

Configuration key: `component.rarity`.

Accepts `COMMON`, `UNCOMMON`, `RARE` or `EPIC`.

```yaml
component:
  rarity: EPIC
```

## Repair Cost - 1.21.5+

Configuration key: `component.repair-cost`.

Sets the prior-work penalty used by an anvil. Use a non-negative integer.

```yaml
component:
  repair-cost: 7
```

## Enchantable - 1.21.5+

Configuration key: `component.enchantable`.

Sets the enchantability value. Use a non-negative integer.

```yaml
component:
  enchantable: 20
```

## Break Sound - 1.21.5+

Configuration key: `component.break-sound`.

Sets the namespaced sound key played when the item breaks. Test with a damageable item without `unbreakable: true`.

```yaml
component:
  break-sound: minecraft:block.glass.break
```

## Enchantments - 1.21.5+

Configuration key: `component.enchants`.

Maps enchantment registry IDs to levels. These are the item’s active enchantments.

```yaml
component:
  enchants:
    sharpness: 5
    unbreaking: 3
```

## Stored Enchantments - 1.21.5+

Configuration key: `component.stored-enchants`.

Maps enchantment registry IDs to stored levels, as used by enchanted books.

```yaml
component:
  stored-enchants:
    sharpness: 4
    mending: 1
```

## Hidden Tooltip Components - 1.21.5+

Configuration key: `component.hide-tooltip`.

Lists native component registry IDs to hide in the tooltip. Hiding the tooltip does not remove the data or disable its behavior.

```yaml
component:
  hide-tooltip:
    - minecraft:enchantments
    - minecraft:attribute_modifiers
```

## Attribute Modifiers - 1.21.5+

Configuration key: `component.attributes`.

Attribute `type` and modifier `name` are namespaced keys. `slot` uses an equipment slot group such as `mainhand`, `offhand`, `hand`, `head`, `chest`, `legs`, `feet`, `armor` or `any`.

```yaml
component:
  attributes:
    - type: minecraft:attack_damage
      name: mythicchanger:test_damage
      amount: 8.0
      operation: ADD_NUMBER
      slot: mainhand
    - type: minecraft:attack_speed
      name: mythicchanger:test_speed
      amount: -1.5
      operation: ADD_NUMBER
      slot: mainhand
```

Use `ADD_NUMBER`, `ADD_SCALAR` or `MULTIPLY_SCALAR_1` for `operation`.

### Attribute Display - 1.21.6+

Each entry can also use `display-mode: RESET`, `HIDDEN` or `OVERRIDE`. `DEFAULT` is an alias for `RESET`; `TEXT` is an alias for `OVERRIDE`. When no mode is specified, the 1.21.6+ adapter hides the modifier's tooltip display. `OVERRIDE` requires `display-text`:

```yaml
component:
  attributes:
    - type: minecraft:attack_damage
      name: mythicchanger:custom_damage
      amount: 8.0
      operation: ADD_NUMBER
      slot: mainhand
      display-mode: OVERRIDE
      display-text: '<red>Custom attack bonus'
```

## Food - 1.21.5+

Configuration key: `component.food`.

Sets nutrition, saturation and whether the item can be eaten at full hunger. Use `consumable` to configure its use animation, duration and consume effects.

```yaml
component:
  food:
    nutrition: 6
    saturation: 0.6
    can-always-eat: true
```

## Consumables - 1.21.5+

Configuration key: `component.consumable`.

`food` sets nutrition and saturation. `consumable` controls the use animation, duration, sound and consume effects. Include `can-always-eat: true` when testing food at full hunger.

```yaml
material: APPLE
amount: 1
name: '&bTest consumable'
component:
  food:
    nutrition: 2
    can-always-eat: true
  consumable:
    consume-seconds: 1.25
    animation: EAT
    sound: minecraft:entity.generic.eat
    effects:
      '1':
        type: apply-effect
        probability: 1.0
        effects:
          - minecraft:speed,200,0,false,true,false
      '2':
        type: play-sound
        sound: minecraft:entity.player.levelup
```

Consume effects are entries inside `consumable.effects`. Each entry has a `type` and its own settings:

| Type              | Settings                                                               |
| ----------------- | ---------------------------------------------------------------------- |
| `apply-effect`    | `probability` from 0.0 to 1.0, plus an `effects` list                  |
| `play-sound`      | `sound`, a namespaced sound key                                        |
| `random-teleport` | `diameter`, the teleport diameter; old `chance` input is also accepted |
| `clear-effect`    | No additional settings; removes all status effects                     |

A potion effect string is `effect ID,duration in ticks,amplifier,ambient,particles,icon`. Amplifiers start at 0. The first three fields are required; omitted boolean fields default to true. Effects are applied in the configured order. For example, put `clear-effect` before `apply-effect` if the new status effects should remain.

```yaml
component:
  consumable:
    consume-seconds: 1.0
    animation: EAT
    effects:
      '1':
        type: clear-effect
      '2':
        type: apply-effect
        probability: 1.0
        effects:
          - 'minecraft:speed,200,0,false,true,false'
      '3':
        type: random-teleport
        diameter: 4.0
```

Each effect entry adds only its own effect. Saving a consumable uses this same numbered-entry structure.

## Use Cooldown - 1.21.5+

Configuration key: `component.use-cooldown`.

`cooldown-seconds` accepts a non-negative number of seconds, including fractional values such as `1.5`. `cooldown-group` is a namespaced key shared by items in the same cooldown group. Test on a usable item, for example an apple with `food` and `consumable` configured.

```yaml
component:
  use-cooldown:
    cooldown-seconds: 3
    cooldown-group: mythicchanger:component_test
```

## Use Remainder - 1.21.5+

Configuration key: `component.use-reminder`.

The existing configuration key is **`use-reminder`**. Keep that spelling even though the native component is called `use_remainder`. Its value is a complete nested ItemFormat, directly under `use-reminder`, without an extra `item:` wrapper. Material, amount and nested component values are preserved when saved and rebuilt.

```yaml
material: APPLE
amount: 1
name: '&bTest use-reminder'
component:
  food:
    nutrition: 1
    can-always-eat: true
  consumable:
    consume-seconds: 1.0
    animation: EAT
    sound: minecraft:entity.generic.eat
  use-reminder:
    material: GLASS_BOTTLE
    amount: 1
    component:
      name: <yellow>Bottle returned after use
```

## Tool - 1.21.5+

Configuration key: `component.tool`.

Each rule string is `block ID[,additional block IDs],speed,correct-for-drops`. Use `true`, `false` or `null` for the last field. Use namespaced block IDs.

```yaml
component:
  tool:
    damage-per-block: 1
    mining-speed: 4.0
    destroy-blocks-in-creative: true
    rules:
      - minecraft:stone,minecraft:deepslate,12.0,true
      - minecraft:dirt,6.0,false
```

## Equippable - 1.21.5+

Configuration key: `component.equippable`.

```yaml
material: LEATHER_CHESTPLATE
amount: 1
name: '&bTest equippable'
component:
  equippable:
    slot: CHEST
    equip-sound: minecraft:item.armor.equip_leather
    asset-id: minecraft:leather
    allowed-entities:
      - minecraft:player
    dispensable: true
    swappable: true
    damage-on-hurt: true
    equip-on-interact: false
```

### Shearing Options - 1.21.6+

These additional equipment options require Paper 1.21.6+:

```yaml
component:
  equippable:
    slot: CHEST
    can-be-sheared: true
    shear-sound: minecraft:entity.sheep.shear
```

## Glider - 1.21.5+

Configuration key: `component.glider`.

Adds gliding behavior when `true`. Use an appropriate wearable item with `equippable.slot: CHEST` when testing.

```yaml
component:
  glider: true
```

## Dyed Color - 1.21.5+

Configuration key: `component.leather-color`.

Sets the leather dye color. Accepts a quoted hex string such as `'#55AAFF'`, an RGB string such as `'85,170,255'`, or an RGB integer string.

```yaml
component:
  leather-color: '#55AAFF'
```

## Armor Trim - 1.21.5+

Configuration key: `component.trim`.

Sets armor trim material and pattern using namespaced registry IDs. Both IDs must exist on the server.

```yaml
component:
  trim:
    material: minecraft:diamond
    pattern: minecraft:sentry
```

## Damage Resistance - 1.21.5+

Configuration key: `component.damage-resistant`.

A string value refers to a damage type tag without a leading `#`, such as `minecraft:is_fire`.

```yaml
component:
  damage-resistant: minecraft:is_fire
```

### Damage Type List - 26.1+

A list contains individual damage type IDs instead of a tag string. These are different formats: `minecraft:is_fire` is a tag, while `minecraft:in_fire` is an individual damage type.

```yaml
component:
  damage-resistant:
    - minecraft:in_fire
    - minecraft:on_fire
```

## Blocks Attacks - 1.21.5+

Configuration key: `component.blocks-attacks`.

Configures blocking behavior. `block-delay-seconds` is a numeric delay in seconds; `block-sound` is a separate namespaced sound key. A string `bypassed-by` value refers to a damage type tag without a leading `#`.

```yaml
component:
  blocks-attacks:
    block-delay-seconds: 0.25
    disable-cooldown-scale: 1.0
    block-sound: minecraft:item.shield.block
    bypassed-by: minecraft:bypasses_shield
```

### Bypassed Damage Type List - 26.1+

Use a list of individual damage type IDs for `bypassed-by` on Paper 26.1+.

```yaml
component:
  blocks-attacks:
    block-delay-seconds: 0.25
    bypassed-by:
      - minecraft:arrow
      - minecraft:trident
```

## Weapon - 1.21.5+

Configuration key: `component.weapon`.

Configures durability damage per attack and how long the weapon disables blocking.

```yaml
component:
  weapon:
    damage-per-attack: 2
    disable-blocking-seconds: 3.0
```

## Bundle Contents - 1.21.5+

Configuration key: `component.bundle-contents`.

Each named or numbered entry is a complete ItemFormat with `material`, `amount` and an optional `component` section. Saving and rebuilding must retain the nested item types, amounts and component data.

```yaml
material: BUNDLE
amount: 1
name: '&bTest bundle-contents'
component:
  bundle-contents:
    '1':
      material: DIAMOND
      amount: 2
      component:
        name: <aqua>Diamond inside bundle
    '2':
      material: EMERALD
      amount: 3
```

## Charged Projectiles - 1.21.5+

Configuration key: `component.charged-projectiles`.

Each named or numbered child is a projectile ItemFormat. Do not put a single `material` directly under `charged-projectiles`. A saved and rebuilt crossbow should retain its configured projectile.

```yaml
material: CROSSBOW
amount: 1
name: '&bTest charged-projectiles'
component:
  charged-projectiles:
    '1':
      material: ARROW
      amount: 1
```

## Banner Patterns - 1.21.5+

Configuration key: `component.banner-patterns`.

Each list entry uses `pattern registry ID: DYE_COLOR`. Patterns are applied in the configured order.

```yaml
component:
  banner-patterns:
    - 'minecraft:stripe_bottom: RED'
    - 'minecraft:cross: BLUE'
    - 'minecraft:border: BLACK'
```

## Potion Contents - 1.21.5+

Configuration key: `component.potion`.

`base-effect` uses a `PotionType` enum value. Custom effects use `effect ID,duration in ticks,amplifier,ambient,particles,icon`; the effect ID is namespaced and amplifiers start at 0.

```yaml
component:
  potion:
    base-effect: SWIFTNESS
    color: '#55FFFF'
    name: component_test
    effects:
      - minecraft:strength,600,1,false,true,true
      - minecraft:regeneration,200,0,false,true,false
```

## Potion Duration Scale - 1.21.5+

Configuration key: `component.potion-duration-scale`.

Multiplies the duration of potion effects. Test on an item with potion contents.

```yaml
component:
  potion-duration-scale: 2.0
```

## Suspicious Stew Effects - 1.21.5+

Configuration key: `component.suspicious-stew-effects`.

Each entry needs only `effect ID,duration in ticks`. Older entries with additional fields remain readable; those extra fields do not change the stew effect.

```yaml
component:
  suspicious-stew-effects:
    - minecraft:night_vision,200
    - minecraft:saturation,20
```

## Fireworks - 1.21.5+

Configuration key: `component.firework`.

Use `trail`, not `trial`. Flight `duration` is inside `firework`, alongside the numbered effect entries; it accepts 0–255.

```yaml
component:
  firework:
    duration: 2
    '1':
      type: STAR
      flicker: true
      trail: true
      colors:
        base:
          - '#FF5555'
          - '#55FF55'
        fade:
          - '#5555FF'
```

## Axolotl Variant - 1.21.5+

Configuration key: `component.axolotl-variant`.

Sets the axolotl bucket variant using an enum value such as `BLUE` or `LUCY`. Test with `AXOLOTL_BUCKET`.

```yaml
component:
  axolotl-variant: BLUE
```

## Tropical Fish Base Color - 1.21.5+

Configuration key: `component.tropical-fish-base-color`.

Sets the tropical fish bucket’s body dye color. Test with `TROPICAL_FISH_BUCKET`.

```yaml
component:
  tropical-fish-base-color: ORANGE
```

## Tropical Fish Pattern Color - 1.21.5+

Configuration key: `component.tropical-fish-pattern-color`.

Sets the tropical fish bucket’s pattern dye color. Test with `TROPICAL_FISH_BUCKET`.

```yaml
component:
  tropical-fish-pattern-color: BLUE
```

## Tropical Fish Pattern - 1.21.5+

Configuration key: `component.tropical-fish-pattern`.

Sets the tropical fish bucket’s pattern enum, such as `KOB`.

```yaml
component:
  tropical-fish-pattern: KOB
```

## Player Profile - 1.21.5+

Configuration key: `component.skull`.

`skull` (or `skull-meta`) is a base64 texture property in this Paper component format, rather than a player-name lookup. Texture display also depends on the client being able to load the texture. Test with `PLAYER_HEAD`.

```yaml
component:
  skull: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvN2YzZmVkMTZmZDU1MTkwOWZhNWUyOWNkZDY5N2VlMzQ2ZTYzMzkwYjM4M2E0MzAwYTY2MmE4MGI2NGQ5ZWIxNyJ9fX0=
```

## Instrument - 1.21.5+

Configuration key: `component.music`.

Sets a registered instrument using its namespaced ID. Test with `GOAT_HORN`.

```yaml
component:
  music: minecraft:ponder_goat_horn
```

## Jukebox Playable - 1.21.5+

Configuration key: `component.song`.

Sets a registered jukebox song using its namespaced ID. Test by inserting the item into a jukebox.

```yaml
component:
  song: minecraft:cat
```

## Ominous Bottle Amplifier - 1.21.5+

Configuration key: `component.ominous-bottle-amplifier`.

Accepts 0–4. Test with `OMINOUS_BOTTLE`.

```yaml
component:
  ominous-bottle-amplifier: 2
```

## Item Model - 1.21.5+

Configuration key: `component.item-model`.

Sets the namespaced item model key. Custom models require matching resource pack assets; the key alone does not create a model.

```yaml
component:
  item-model: minecraft:diamond_sword
```

## Tooltip Style - 1.21.5+

Configuration key: `component.tooltip-style`.

Sets a custom tooltip style key. The spelling is `tooltip-style`, not `tootip-style`. A matching resource pack asset is required to change its appearance.

```yaml
component:
  tooltip-style: minecraft:component_test
```

## Attack Range - 1.21.11+

Configuration key: `component.attack-range-key`.

The configuration key is **`attack-range-key`**. Reach values accept 0–64, `hitbox-margin` accepts 0–1, and `mob-factor` accepts 0–2.

```yaml
component:
  attack-range-key:
    min-reach: 0.0
    max-reach: 4.0
    min-creative-reach: 0.0
    max-creative-reach: 5.0
    hitbox-margin: 0.3
    mob-factor: 1.0
```

## Damage Type - 1.21.11+

Configuration key: `component.damage-type`.

Sets the weapon’s damage type using an individual damage type registry ID, rather than a damage type tag.

```yaml
component:
  damage-type: minecraft:player_attack
```

## Kinetic Weapon - 1.21.11+

Configuration key: `component.kinetic-weapon`.

Configures kinetic weapon contact cooldown, delay, movement, damage multiplier, sounds and conditions. Condition durations are measured in ticks. Test separately from other components that change the same attack interaction.

```yaml
component:
  kinetic-weapon:
    contact-cooldown-ticks: 10
    delay-ticks: 2
    forward-movement: 0.3
    damage-multiplier: 1.5
    sound: minecraft:entity.player.attack.sweep
    hit-sound: minecraft:entity.player.attack.knockback
    damage-conditions:
      max-duration-ticks: 20
      min-speed: 0.15
      min-relative-speed: 0.1
    knockback-conditions:
      max-duration-ticks: 30
      min-speed: 0.12
      min-relative-speed: 0.08
    dismount-conditions:
      max-duration-ticks: 15
      min-speed: 0.2
      min-relative-speed: 0.1
```

## Minimum Attack Charge - 1.21.11+

Configuration key: `component.minimum-attack-charge`.

Accepts a value from 0 to 1 for the minimum attack charge.

```yaml
component:
  minimum-attack-charge: 0.65
```

## Piercing Weapon - 1.21.11+

Configuration key: `component.piercing-weapon`.

Configures piercing weapon knockback, dismount behavior and sounds.

```yaml
component:
  piercing-weapon:
    deals-knockback: true
    dismounts: true
    sound: minecraft:entity.player.attack.sweep
    hit-sound: minecraft:entity.player.attack.strong
```

## Swing Animation - 1.21.11+

Configuration key: `component.swing-animation`.

Configures the legacy swing animation. On Paper 1.21.11 through 26.2 this supplies the swing component. On Paper 26.3+ it supplies both attack and interact animations, except where an explicit `attack-animation` or `interact-animation` section overrides its respective side.

```yaml
component:
  swing-animation:
    type: NONE
    duration: 7
```

## Use Effects - 1.21.11+

Configuration key: `component.use-effects`.

Configures sprinting, interaction vibrations and movement speed while using the item. `speed-multiplier` accepts 0–1. Test on a usable item with a use duration, for example an apple with `food` and `consumable` configured.

```yaml
component:
  use-effects:
    can-sprint: true
    interact-vibrations: false
    speed-multiplier: 0.4
```

## Sulfur Cube Content - 26.2+

Configuration key: `component.sulfur-cube-content`.

The content is a complete nested ItemFormat.

```yaml
component:
  sulfur-cube-content:
    material: DIAMOND
    amount: 1
```

## Attack Animation - 26.3+

Configuration key: `component.attack-animation`.

Sets the attack animation independently. Takes precedence over `swing-animation` for attack behavior.

```yaml
component:
  attack-animation:
    type: NONE
    duration: 9
```

## Interact Animation - 26.3+

Configuration key: `component.interact-animation`.

Sets the interaction animation independently. Takes precedence over `swing-animation` for interaction behavior.

```yaml
component:
  interact-animation:
    type: NONE
    duration: 5
```

## Sign Text Front - 26.3+

Configuration key: `component.sign-text-front`.

Configures the front side of a sign. Use four lines, a dye color and `glowing` as needed. Test by placing an `OAK_SIGN` item.

```yaml
component:
  sign-text-front:
    lines:
      - Front line 1
      - Front line 2
      - Front line 3
      - Front line 4
    color: RED
    glowing: true
```

## Sign Text Back - 26.3+

Configuration key: `component.sign-text-back`.

Configures the back side of a sign. Use four lines, a dye color and `glowing` as needed. Test by placing an `OAK_SIGN` item.

```yaml
component:
  sign-text-back:
    lines:
      - Back line 1
      - Back line 2
      - Back line 3
      - Back line 4
    color: BLUE
    glowing: true
```

## Waxed - 26.3+

Configuration key: `component.waxed`.

Use `true` to add the waxed state to a sign item. Check whether the placed sign is sealed against editing.

```yaml
component:
  waxed: true
```

## Cushion Color - 26.3+

Configuration key: `component.cushion-color`.

Sets the cushion dye color using a dye color enum such as `RED`. Use an appropriate material and interaction to check the visible result.

```yaml
component:
  cushion-color: RED
```

## Villager Food - 26.3+

Configuration key: `component.villager-food`.

Sets the item’s villager food value. Test the relevant villager interaction with an appropriate item material.

```yaml
component:
  villager-food: 4
```

## Provides Pottery Pattern - 26.3+

Configuration key: `component.provides-pottery-pattern`.

Sets a decorated pot pattern using its namespaced registry ID. The pattern must exist on the server.

```yaml
component:
  provides-pottery-pattern: minecraft:angler
```

## Mob Visibility - 26.3+

Configuration key: `component.mob-visibility`.

Applies a visibility factor to the listed entity types. `visibility` accepts 0–10. Entity IDs must exist in the server registry.

```yaml
component:
  mob-visibility:
    entities:
      - minecraft:zombie
      - minecraft:skeleton
    visibility: 0.5
```

## Saving and testing

Set `debuild-item-method: COMPONENT` in `config.yml` and reload the plugin to save supported item properties inside a `component` section. This setting does not change how Minecraft stores the item itself.

For file installation, give commands, round-trip checks and version-specific examples, continue to [Testing Paper Components](/format/itemformat-tm/component-testing).


# Testing Paper Components

Use a server running the Paper version you want to test and MythicChanger Premium. Configuration parsing and a successful plugin build do not verify game behavior. Check the item data, the visible result and a save/rebuild cycle separately.

## Choose a version-specific ItemFormat

Each sample is a complete ItemFormat. Download or copy its raw YAML content, then save it as `plugins/MythicChanger/items/pct-all.yml`:

| Server version | Example                                                                                                                             |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Paper 1.21.5   | [1.21.5 component test](https://github.com/ManyouTeam/MythicChanger/tree/master/docs/format/examples/paper-1.21.5-components.yml)   |
| Paper 1.21.6   | [1.21.6 component test](https://github.com/ManyouTeam/MythicChanger/tree/master/docs/format/examples/paper-1.21.6-components.yml)   |
| Paper 1.21.11  | [1.21.11 component test](https://github.com/ManyouTeam/MythicChanger/tree/master/docs/format/examples/paper-1.21.11-components.yml) |
| Paper 26.1     | [26.1 component test](https://github.com/ManyouTeam/MythicChanger/tree/master/docs/format/examples/paper-26.1-components.yml)       |
| Paper 26.2     | [26.2 component test](https://github.com/ManyouTeam/MythicChanger/tree/master/docs/format/examples/paper-26.2-components.yml)       |
| Paper 26.3     | [26.3 component test](https://github.com/ManyouTeam/MythicChanger/tree/master/docs/format/examples/paper-26.3-components.yml)       |

These samples combine many supported components for data inspection. They omit the head profile, nested bundle/projectile/remainder tests and selected tooltip options so that those can be checked separately. They cover the plugin's supported configuration, rather than every native Minecraft component or every possible value.

Install only the sample matching your server version under this file name. A newer sample on an older server can leave unsupported options unapplied. Do not interpret that as a successful test of those components.

Reload and give yourself the item:

```
/mc reload
/mc givesaveitem pct-all
```

For a console command, include an online player name:

```
mc givesaveitem pct-all PlayerName 1
```

The give command requires `mythicchanger.givesaveitem`. The item ID is the file name without `.yml`; do not include the `items/` path in the command.

## Inspect the generated data

Hold the item in your main hand and run:

```
/data get entity @s SelectedItem.components
```

Run this as a player with access to the vanilla `data` command. The native component names use underscores, while the plugin's YAML configuration usually uses hyphens. For example, `custom-model-data` is written to `minecraft:custom_model_data`.

Check the relevant component values rather than only whether the item exists. A component might be stored without producing a visible effect on the sample's `DIAMOND_SWORD` material.

The combined sample is not a reliable way to test every interaction at once. Equipping, blocking and eating can compete for the same use action. It also includes `unbreakable: true`, so it should not be used to test normal durability loss. For behavior tests, use a separate item with an appropriate material and only the component being tested, plus its prerequisites.

## Save and rebuild the item

In `config.yml`, set:

```yaml
debuild-item-method: COMPONENT
```

Reload the plugin. Hold the test item and run:

```
/mc generateitemformat
```

The command writes `plugins/MythicChanger/generated-item-format.yml`. It requires `mythicchanger.generateitemformat` and overwrites the same file on every use, so copy each result before testing another item.

Copy the generated file to `plugins/MythicChanger/items/pct-roundtrip.yml`, then run:

```
/mc reload
/mc givesaveitem pct-roundtrip
```

Hold the rebuilt item and inspect `SelectedItem.components` again. Compare component values, quantities and behavior. YAML key order, explicit defaults and generated player-profile UUIDs can differ without changing the intended item properties.

You can also save directly into the `items` folder:

```
/mc saveitem pct-roundtrip itemformat
/mc givesaveitem pct-roundtrip
```

Saving requires `mythicchanger.saveitem`. The `itemformat` save method follows `debuild-item-method`; the `bukkit` save method uses the separate item serialization path and does not exercise the component-to-ItemFormat writer.

## Focused checks

| Test                                | Expected result                                                                                                                       |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Custom model data                   | Each configured float, flag, string and color appears once and keeps its order after saving and rebuilding                            |
| Consumable effects                  | Each numbered effect adds only its configured type; effect duration, amplifier, particles and icon flags survive a save/rebuild cycle |
| Suspicious stew                     | `effect ID,duration` entries work without a third field                                                                               |
| Blocking                            | Saved `block-delay-seconds` remains a number, independent of `block-sound`                                                            |
| Damage resistance, Paper 26.1+      | A tag string and a list of individual damage IDs both preserve their respective formats                                               |
| Attributes, Paper 1.21.6+           | Explicit `RESET`, `HIDDEN` and `OVERRIDE` modes produce the intended tooltip display                                                  |
| Weapon components, Paper 1.21.11+   | Inspect the configured reach, charge, kinetic/piercing weapon and use-effect data; test each behavior separately                      |
| Animation compatibility, Paper 26.3 | `swing-animation` supplies both native animations; explicit attack/interact sections override their own side                          |
| Signs, Paper 26.3                   | Placed signs retain the configured front/back text, dye colors, glowing state and wax                                                 |

For a consumable effect test, use the complete apple example in [Consumables - 1.21.5+](/format/itemformat-tm/component-format#consumables). It should apply Speed I for 200 ticks and play a level-up sound. It should not also teleport the player or remove effects unless those types were configured. Test in survival mode.

## Nested-item regression examples

Save each example in its own `items/<ID>.yml` file and use `/mc givesaveitem <ID>` to obtain it. Run the save/rebuild procedure for each item.

### Bundle contents

Save as `pct-bundle.yml`:

```yaml
material: BUNDLE
amount: 1

component:
  bundle-contents:
    '1':
      material: DIAMOND
      amount: 2
      component:
        name: '<aqua>Diamond inside bundle'
    '2':
      material: EMERALD
      amount: 3
```

The bundle should contain two diamonds and three emeralds. The diamonds should retain their custom name. Nested entries must not turn into stone or lose their amounts.

### Charged crossbow

Save as `pct-projectile.yml`:

```yaml
material: CROSSBOW
amount: 1

component:
  charged-projectiles:
    '1':
      material: ARROW
      amount: 1
```

The crossbow should contain an arrow and remain loaded after rebuilding. Test shooting it separately from the saved data inspection.

### Item returned after consumption

Save as `pct-remainder.yml`:

```yaml
material: APPLE
amount: 1

component:
  food:
    nutrition: 1
    can-always-eat: true

  consumable:
    consume-seconds: 1.0
    animation: EAT
    sound: minecraft:entity.generic.eat

  use-reminder:
    material: GLASS_BOTTLE
    amount: 1
    component:
      name: '<yellow>Bottle returned after use'
```

Eat the apple in survival mode. It should return a named glass bottle. After saving and rebuilding the unused apple, it should still return the same item. The saved `use-reminder` must contain the nested ItemFormat directly, without an additional `item:` wrapper.

## Resource packs and reports

Custom model data, custom item models and custom tooltip styles need matching resource pack assets to change appearance. A missing visual asset does not establish that the component failed to write. Use registry IDs that exist on the tested server, including any data packs it loads.

When reporting a problem, include the exact Paper build, MythicChanger version, original ItemFormat, generated ItemFormat, relevant item component data and any console exception. State whether the problem occurs while giving, using, saving or rebuilding the item. Do not report all six versions as tested when only their configuration files were parsed.


# 🎬Action Format

{% hint style="info" %}
The `actions` in the **Action Format** **example** only represent **Action Format** start from here. Please refer to the page description of the corresponding function for specific option names, such as `real-change-actions`.
{% endhint %}

## Available Placeholders

* {world}
* {player\_x}
* {player\_y}
* {player\_z}
* {player\_pitch}
* {player\_yaw}
* {player}

Please note that **MythicChanger** supports use [Powerful Item ](/features/powerful-item-placeholders)[Placeholder](/features/powerful-item-placeholders) at ActionFormat.

## Sound

Send sound to player.

```yaml
    actions:
      1:
        type: sound
        sound: 'ui.button.click'
        volume: 1
        pitch: 1
```

## Message

Send a message to the player, support color code.

```yaml
    actions:
      1:
        type: message
        message: 'Hello!'
```

## Title

Send title to the player, support the color code.

```yaml
    actions:
      1:
        type: title
        main-title: 'Good day'
        sub-title: 'Not bad'
        fade-in: 10
        stay: 70
        fade-out: 30
```

## Particle

```yaml
    actions:
      1: 
        type: particle
        particle: HEART
        count: 20
        offset-x: 0.3
        offset-y: 1.0
        offset-z: 0.3
        speed: 0.01
```

## Announcement

Send a message to all online players, support color code.&#x20;

```yaml
    actions:
      1:
        type: announcement
        message: 'Hello!'
```

## Effect

Give players potion effect.

```yaml
    actions:
      1:
        type: effect
        potion: BLINDNESS
        duration: 60
        level: 1
        ambient: true # Optional
        particles: true # Optional
        icon: true # Optional
```

## Teleport

Teleport player to specified location.

```yaml
    actions:
      1:
        type: teleport
        world: LobbyWorld
        x: 100
        y: 30
        z: 300
        pitch: 90 # Optional
        yaw: 0 # Optional
```

## Player Command

Make the player excutes a command.

```yaml
    actions:
      1:
        type: player_command
        command: 'tell Hello!'
```

## Op Command

Make the player excutes a command as OP.

```yaml
    actions:
      1:
        type: op_command
        command: 'tell Hello!'
```

## Console Command

Make the console excutes a command.

```yaml
    actions:
      1:
        type: console_command
        command: 'op {player}'
```

## Spawn vanilla mobs

Spawn vanilla mobs.

```yaml
    actions:
      1:
        type: entity_spawn
        entity: ZOMBIE
        world: LOBBY # Optional
        x: 100.0 # Optional
        y: 2.0 # Optional
        z: -100.0 # Optional
```

## Delay <mark style="color:red;">- Premium</mark>

Make the action run after X ticks.

```yaml
    actions:
      1:
        type: delay
        time: 50
        wait-for-player: true
        actions:
          1:
            type: entity_spawn
            entity: ZOMBIE
```

## Chance <mark style="color:red;">- Premium</mark>

Set the chance the action will be excuted, up to 100. 50 means this action has 50% chance to excute.

```yaml
    actions:
      1:
        type: chance
        rate: 50
        actions:
          1:
            type: entity_spawn
            entity: ZOMBIE
```

## Any <mark style="color:red;">- Premium</mark>

Randomly choose a action to execute.

```yaml
    actions:
      1:
        type: any
        amount: 2
        actions:
          1:
            type: entity_spawn
            entity: ZOMBIE
          2:
            type: entity_spawn
            entity: SKELETON
          3:
            type: entity_spawn
            entity: WITHER
```


# ⚖️Condition Format

## Available Placeholders

* {world}
* {player\_x}
* {player\_y}
* {player\_z}
* {player\_pitch}
* {player\_yaw}
* {player}

Please note that **MythicChanger** supports use [Powerful Item ](/features/powerful-item-placeholders)[Placeholder](/features/powerful-item-placeholders) at ConditionFormat.

```yaml
  conditions:
    1:
      type: permission
      permission: 'group.vip'
```

## World

Player must be in the world.

<pre class="language-yaml"><code class="lang-yaml"><strong>  conditions:
</strong>    1:
      type: world
      world: lobby
</code></pre>

## Biome

Player must be in the biome.

```yaml
  conditions:
    1:
      type: biome
      biome: oraxen
```

## Permission

Player must has the permission.

**Remember that OP players will always have all permissions unless plugin set it not by default, so if you want to test this condition, you have to deop yourself.**

```yaml
  conditions:
    1:
      type: permission
      permission: 'group.vip'
```

## Placeholder

Player must be meet the placeholder condition.

Rule can be set to:

* \>=
* <=
* \>
* <
* \== (String)
* \= (Number)
* != (Number or string)
* !\*= (Number or string) Not contains.
* \*= (String) Contains, for example, str \*= string is true, but example \*= ple is false.

```yaml
  conditions:
    1:
      type: placeholder
      placeholder: '%player_health%'
      rule: '<='
      value: 5
```

## Any <mark style="color:red;">- Premium</mark>

```yaml
  conditions:
    1:
      type: any
      conditions:
        1:
          type: placeholder
          placeholder: '%eco_balance%'
          rule: '>='
          value: 200
        2:
          type: placeholder
          placeholder: '%player_points%'
          rule: '>='
          value: 400
```

## Not <mark style="color:red;">- Premium</mark>

```yaml
  conditions:
    1:
      type: not
      conditions:
        1:
          type: placeholder
          placeholder: '%eco_balance%'
          rule: '>='
          value: 200
```


# ➗Math Calculate Format

The **Math Calculate Format** provided by **MythicChanger** are almost identical to those in UltimateShop. Therefore, they will not be elaborated on in this wiki. Please refer to UltimateShop's wiki for a detailed introduction about them. Click [here](https://ultimateshop.superiormc.cn/format) to view.


# 📂Info of Auto Match & Change

The Auto Match\&Change feature refers to the plugin automatically recognizing all items of all players. Once a player's item meets the set matching requirements, it will undergo fake or real change.

Some common uses include:

* Automatically add rarity tags to all items.&#x20;
* Remove the enchantment added abnormally.&#x20;
* Remove suspected abnormal items.&#x20;
* Add the texture of the tooltip at the lore & name of the item.

## Fake Change and Real Change

The modification of items is divided into fake change and real change.

Fake change is display virtually, and it only change in client side. This means the modified content is only valid for the client. For the server, these modifications are false and have not actually taken effect.&#x20;

Real change is change both in client and server side, **modification of changes is not immediate in some time, but mostly in survival mode, real change is "immediate".**

For example, if you are using remove\_enchants change rule, if you set this rule in fake changes, item just display it don't have this enchantment, but actually it has and the enchantment will also take effect. If you set it in real change, then the enchantment will actually gone. No one will find it anymore.

## Rule

The Auto Match\&Change feature is implemented by various **rule** configuration files, which mainly include:

* Match Item: Set matching items through various **match rules**.
* Fake/Real Changes: The matched items will undergo **fake change and real change** according to the **change rule**.


# 📌Rule

Rule determines which items need to be modified and what they look like are determined by each rule in Auto Match\&Change feature.

## Rule Configs

All rules are existed at `rules` folder, you can copy `default.yml` to rename it to other words to create a new rule.

```yaml
weight: 15

only-in-player-inventory: true

# If you want to all item apply this rule, just delete whole match_item section.
match-item:
  items:
    - 'diamond_sword'
  # Whether you use item tier instead of item ID to identify item slots.
  # If this item plugin don't have tier, will still use Item ID as identify.
  #use-tier-identify: true
  #has-name: true
  #has-lore: true
  #contains-lore:
  #  - 'test'
  #contains-name:
  #  - 'test'

fake-changes:
  add-name-first: '&fGood '
  #set-name: '&fGood Diamond Sword'
  #add-lore:
  #  - '&f&lCommon'
  #set-lore:
  #  - '&7A good sword that all adventures should use!'
  #  - '&f&lCommon'
  #add-lore-prefix:
  #  - '%img_tooltip1%'
  #set-custom-model-data: 5
  #add-flags:
  #  - 'HIDE_ENCHANTS'

real-changes:
  add-enchants:
    KNOCKBACK: 1
  #remove-enchants:
  #  - 'POWER'
  #remove-all-enchants: true
  #delete-enchants:
  #  POWER: 3
  #replace-item:
  #  material: golden_sword
  
real-change-actions:
  1:
    type: message
    message: '&#98FB98[MythicChanger] &fChanged item!'

conditions:
  1:
    type: permission
    permission: 'mythicchanger.admin'
```

## General Options

* `weight` option represents this rule apply weight.
* `match-item` option represents which items will trigger this rule.
* `fake-changes` option represents what content will be modified at the client level.&#x20;
* `real-changes` option represents what content will be modified both in the client and server.
* `real-change-actions` option represents the action will executed when we applying real changes. Use **Action Format** here, for more info, please view [Format](/format/action-format) page. <mark style="color:red;">**PREMIUM VERSION ONLY.**</mark>
* `conditions` option represents players must meet those conditions to apply this rule. Use **Condition Format** here, for more info, please view [Format](/format/action-format) page.  <mark style="color:red;">**PREMIUM VERSION ONLY.**</mark>
* If you don't want to make fake or real change, you need delete the whole section instead of put empty value there!


# 📚Rule Config Example - Lore Modifier

## Config

```yaml
weight: 15

# If you want to all item apply this rule, just delete whole match_item section.
match-item:
  items:
   - 'diamond_sword'

fake-changes:
  set-name: '&fGood Diamond Sword'
  set-lore:
    - '&7A good sword that all adventures should use!'
    - '&f&lCommon'
  add-lore-prefix: '1'

real-changes:
  add-enchants:
    KNOCKBACK: 1
  remove-enchants:
    - 'POWER'
```

## In-game showcase

<figure><img src="https://2518436866-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FECy8m2ZXGWwelMAR2Swy%2Fuploads%2F2vI3NJQT4e1Lalba8Kwm%2Fimage.png?alt=media&amp;token=a55ba50a-6d0f-454d-b10e-1443df6db83d" alt=""><figcaption></figcaption></figure>


# 📚Rule Config Example - Vanilla Item Replacer

## Config

```yaml
weight: 15

# If you want to all item apply this rule, just delete whole match_item section.
match-item:
  items:
   - 'iron_sword'
  # Whether you use item tier instead of item ID to identify item slots.
  # If this item plugin don't have tier, will still use Item ID as identify.
  use-tier-identify: false

fake-changes:
  replace-item:
    hook-plugin: MMOItems
    hook-item: WAND;;OAK_WAND
    keep-enchants: true

real-changes:
  replace-item:
    hook-plugin: MMOItems
    hook-item: WAND;;OAK_WAND
    keep-enchants: true
```

## In-game showcase

<figure><img src="https://2518436866-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FECy8m2ZXGWwelMAR2Swy%2Fuploads%2FPeSj4yglQ7CU2Bk1lVJw%2Fimage.png?alt=media&amp;token=083253fd-0168-4093-945c-7362220667ec" alt=""><figcaption></figcaption></figure>


# 📚Rule Config Example - Illegal Enchant Level Remover

In this example, enchant level higher than 6 will be replaced to level 3.

{% hint style="info" %}
This example file will only work for <mark style="color:red;">**PREMIUM**</mark> version of **MythicChanger**.
{% endhint %}

## Config

```yaml
weight: 15

only-in-player-inventory: false

match-item:
  contains-enchants:
    UNBREAKING: 6

real-changes:
  add-enchants:
    UNBREAKING: 3
  add-enchants-ignore-level: true

real-change-actions:
  1:
    type: message
    message: '&#98FB98[MythicChanger] &fModified illegal enchantment level!'

conditions:
  1:
    type: permission
    permission: 'mythicchanger.admin'
```


# 📚Rule Config Example - Random Replace

{% hint style="info" %}
This example file will only work for <mark style="color:red;">**PREMIUM**</mark> version of **MythicChanger**.
{% endhint %}

```yaml
weight: 15

match-item:
  material:
    - iron_sword
  has-name: false

fake-changes: 
  replace-item:
    material: iron_sword
    name: '&c???'
    lore:
      - '&fNo one knows what sword'
      - '&fyou will obtain...'

real-changes: 
  replace-random-item:
    1:
      material: iron_sword
      amount: 1
      name: §fSharp §fLong Sword
      lore:
      - §cSword
      - §f
      - §eRequires Lvl 0
      - §f
      - '§3 §7➸ Attack Damage: §f8.1'
      - '§3 §7➸ Attack Speed: §f1.6'
      - §f
      - §c🔥§7 10 Fire Damage
      - §7Much sharper!
      flags:
      - HIDE_ATTRIBUTES
      attributes:
        - type: GENERIC_ATTACK_SPEED
          name: decoy
          amount: 0.0
          operation: ADD_NUMBER
          slot: any
      rate: 1
    2:
      material: iron_sword
      amount: 1
      name: §fKatana
      lore:
      - §cSword
      - §f
      - '§3 §7➸ Attack Damage: §f7'
      - '§3 §7➸ Attack Speed: §f2'
      - '§3 §7■ Crit Strike Chance: §f+10%'
      - '§3 §7■ Movement Speed: §f+2'
      - §f
      - §7§oA very sharp & light sword
      - §7§oforged by a hundred years
      - §7§oof smithing mastery.
      - §f
      - '§3 §7Tier: §6§lRARE'
      - '§7Durability: 800 / 800'
      flags:
      - HIDE_ATTRIBUTES
      attributes:
        - type: GENERIC_ATTACK_SPEED
          name: decoy
          amount: 0.0
          operation: ADD_NUMBER
          slot: any
      rate: 1

real-change-actions: []

conditions: []
    
only-in-player-inventory: false
```


# 📂Info of Drag/GUI Change

Sometimes you want players to modify their items independently, and this feature is born.  The Drag/GUI Change feature refers to plugin create the **apply item**, your players can use **apply item** to change their items. Each **apply item** can be configured with which items can use it, and what modifications will be made to the items after using the **apply item**. In one word: Players can modify items through the Apply Item instead of using the matching rules set in the rule configuration.

Some common uses include:

* Item Skiner - By `set-custom-model-data, set-color` rule.
* Deenchanter Item - By `remove-all-enchants` rule. Require `real-changes`. This will remove all enchantments.
* Name Changer - By `set-name` rule.

## Use Method&#x20;

* GUI: Apply items will use in `/mc openchangegui`. <mark style="color:red;">**- Premium**</mark>
* Drag: Drag the apply item to the item you want to changed.

For more info, please view [this page](/drag-gui-change/apply-item-mode).


# 🪄Apply Item

For 2.1.0+: <mark style="color:red;">**Free version can only create up to 3 apply items, please consider buy the premium version if you want to more.**</mark>

## Apply item configs

All apply items are saved in `apply_items` folder, an example file is here:

```yaml
apply-item-mode: GENERAL

# Display Item
display-item:
  material: PAPER
  name: '&#da8f87Attribute Scroll &7(Attack Damage &a+0.5&7)'
  lore:
    - '&8Scroll'
    - ''
    - '&7Drag any &cswords or axes &7onto this item to'
    - '&7make its &bAttack Damage &7value &a+0.5&7.'
    - '&7Up to value &410&7 can be upgraded.'
    - ''
    - '&bSuccess Rate: &a50%'
    - '&a&lRare'
  max-stack: 1
  
# Chance, Up to 100
chance: 50
  
# Rule Configs
fake-changes:
  set-custom-model-data: 50
real-changes:
  add-attributes:
    ATTACK_DAMAGE: 
      name: attack_damage 
      amount: '0.5'
      operation: ADD_NUMBER 
      slot: HAND 

# Apply Rule
apply-rule: example
apply-real-change: false

# Match Item
match-item:
  material-tag:
    - swords

# Conditions
conditions:
  1:
    type: placeholder
    rule: '<'
    placeholder: '{item_attributes.ATTACK_DAMAGE.amount;;0}'
    value: 10
    
# Actions
success-actions:
  1:
    type: message
    message: '&fCool, it looks like magic is showing off, your {name} &fis more powerful now!'
fail-actions:
  1:
    type: message
    message: '&fOh, no! Seems that this time you are now very lucky, the scroll broken, nothing changed!'
```

## General Options

We have those options for apply item!

* apply-item-mode: Please view [this page](/drag-gui-change/apply-item-mode) to know more.
* display-item: The display item of this apply item. Should use [Item Format](https://ultimateshop.superiormc.cn/base/item-format) here.
* match-item: Read Match Rules page for more info, which item can use this apply item, if removed, all items can use this apply item.
* chance: The chance of the apply item be success to use. Can set a number from 0 to 100 here.
* success-actions/fail-actions: The success/fail actions will executed after player use this apply item. Use **Action Format** here, for more info, please view [Format](/format/action-format) page.
* conditions: The conditions player should meet to use the apply item. Use **Condition Format** here, for more info, please view [this page](/format/action-format).

## Apply item types and their specific options

There 2 types of apply items, different type of apply item have different specific options:

* **Rule Change:** Apply item based on [rules](/auto-match-and-change/rule). This means after use apply item, even this item do not meet match requirements of this rule configs, it will still be changed. Supports fake change and real change.
  * apply-rule: Which rule config will use after applied this item.
  * apply-real-change: Whether also apply rule's real changes.
* **Apply Change:** Apply item has it's own changes. This means after use apply item, we will change this item by the apply item config.
  * real-changes: Set the real change after use this apply item.
  * fake-changes: Set the fake change after use this apply item.

## Let the apply item only use the same item once <mark style="color:red;">- Premium</mark>

Start from 2.1.0, we won't prevent player use same apply item repeatly, if you want to this apply rule can only be used for each item once, you need add `contains-apply` rule at `match-item` section. Like:

```yaml
# <Other part of this apply item config>
match-item:
  not:
    contains-apply:
      - 'Write Apply Item ID here'
```

Please note that this only work for fake rule changes, if you are using real-changes, you need to figure out how to fill in the `match-item` option on your own to avoid duplicate matches. For example, if you set a `set-lore` rule, use the `contains-lore` matching rule, which is really very simple.

## Deapply <mark style="color:red;">- Premium</mark>

Want to rollback your modified item? This example apply item can help you!

```yaml
material: BOOK
name: '&fRollback book'
lore:
  - '&7Drag this item onto the item you want to rollback its apply.'
real-changes:
  deapply: true
match-item:
  has-apply: true
```

* You **MUST** set `apply-real-change` option to `false` in apply items config.
* This won't work for **REAL CHANGE**.

## Apply Limit <mark style="color:red;">- Premium</mark>

By default, each item can only use 1 apply item (not means use apply item once, for example, you used apply item A, other apply item B, C, etc can not use on this item, but A still can use) but, you can use new apply item system to avoid that.

* You can use `set-apply-limit`, `add-apply-limit`, `reset-apply-limit` change rules to edit item's apply item.
* Another way is use command `/mc setlimit <amount>` to edit your hold item's apply item. Then use `/mc saveitem <itemID>` command, after that, you can use `/mc givesaveitem <itemID>` command to give the item you edited.


# ⚡Apply Item Mode

## Enable/Disable Apply Item Mode

We support 2 apply item use method, you can enable or disable it at `config.yml` with `apply-item-mode`. With this option, it will work for all apply items in plugin.

* GUI: Apply items will use in `/mc openchangegui`. <mark style="color:red;">**- Premium**</mark>
* DRAG: Drag the apply item to the item you want to changed.

This option change require server restart.

```yaml
apply-item-mode:
  drag-enabled: true
  # GUI mode is in EARLY ALPHA TEST, be careful to use!
  # Premium version only.
  gui-enabled: true
```

## Set apply item mode for each single apply items

If you want to set the apply mode for individual apply items, instead of setting it for all apply items at once as described above, then you need to set the value of the `apply-item-mode` option in `config.yml` to `GENERAL` first.

Then, each apply item configs will include a option called `apply-item-mode` too, set it to the apply use method you want. Supported value:

* GUI: Apply items will use in `/mc openchangegui`. <mark style="color:red;">**- Premium**</mark>
* DRAG: Drag the apply item to the item you want to changed.
* GENERAL: Both GUI and DRAG method can use the apply item. (GUI mode requires PREMIUM version)
* Other Words (Custom Mode): You can enter characters other than **DRAG, GUI, and GENERAL**. For example, if you enter `MY_CUSTOM` here, the player will only be able to use the apply item in the GUI opened by the command `/mc openchangegui MY_CUSTOM`.

{% hint style="info" %}
To open custom mode GUI, player need has mythicchanger.openchangegui.\<customModeName> permission, in this example, to use `/mc openchangegui MY_CUSTOM`, player need has `mythicchanger.openchangegui.MY_CUSTOM` permission.    &#x20;
{% endhint %}

<figure><img src="https://2518436866-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FECy8m2ZXGWwelMAR2Swy%2Fuploads%2FMb4HFhUk7pJE7Fmp9izz%2F1f1642c4fc54ac97e40b9e3dd59e9c56.png?alt=media&amp;token=dfa26d56-669b-4840-9c58-61f4a5c6278c" alt=""><figcaption></figcaption></figure>

## Custom Mode <mark style="color:red;">- Premium</mark>

We've already introduced custom mode above. You can set `apply-item-mode` to a custom value in the apply item config, and then open a custom GUI using `/mc openchangegui` with your custom value. Players will only be able to use these apply items within this custom GUI.

You can also set those custom GUI config at `config.yml` file.

```yaml
# Default Change GUI
change-gui:
  title: 'Change your item!'
  custom-mode-title:
    MY_CUSTOM: 'MY_CUSTOM change GUI'
  size: 27
  item-slot: 11
  book-slot: 15
  confirm-slot: 22
  confirm-item:
    material: ANVIL
    name: '&eConfirm'
    lore:
      - '&7Click to confirm change the item!'
  custom-item:
    2:
      material: PAPER
      name: '&bDrag the item you want change below.'
    6:
      material: BOOK
      name: '&bDrag the apply item below.'
  close-if-fail: true

# MY_CUSTOM GUI
MY_CUSTOM:
  title: 'MY_CUSTOM'
  custom-mode-title:
    MY_CUSTOM: 'MY_CUSTOM change GUI'
  size: 27
  item-slot: 11
  book-slot: 15
  confirm-slot: 22
  confirm-item:
    material: ANVIL
    name: '&eConfirm'
    lore:
      - '&7Click to confirm change the item!'
  custom-item:
    2:
      material: PAPER
      name: '&bDrag the item you want change below.'
    6:
      material: BOOK
      name: '&bDrag the apply item below.'
  close-if-fail: true
```


# 📚Apply Item Example - Enchantment Scroll

{% hint style="info" %}
This example file will only work for <mark style="color:red;">**PREMIUM**</mark> version of **MythicChanger**.
{% endhint %}

<pre class="language-yaml"><code class="lang-yaml"># Display Item
display-item:
  material: PAPER
  name: '&#x26;fEnchantment Scroll &#x26;7(Respiration &#x26;a+1&#x26;7)'
  lore:
    - '&#x26;8Scroll'
    - ''
    - '&#x26;7Drag any &#x26;cenchantable item &#x26;7onto this item to'
    - '&#x26;7make its &#x26;bRespiration &#x26;7level &#x26;a+1&#x26;7.'
    - '&#x26;7Up to level &#x26;410&#x26;7 can be upgraded.'
    - ''
    - '&#x26;buccess Rate: &#x26;a50%'
    - '&#x26;9&#x26;lUncommon'
  max-stack: 1
  
# Chance, Up to 100
chance: '50'
  
# Rule Configs
real-changes:
  add-enchants:
    respiration: '{item_enchants.respiration;;0} + 1'

# Match Item
match-item:
  enchantable:
    - respiration

# Conditions
conditions:
  1:
    type: placeholder
    rule: '&#x3C;'
    placeholder: '{item_enchants.respiration}'
    value: 10
    
<strong># Actions
</strong>success-actions:
  1:
    type: message
    message: '&#x26;fCool, it looks like magic is showing off, your {name} &#x26;fis more powerful now!'
fail-actions:
  1:
    type: message
    message: '&#x26;fOh, no! Seems that this time you are now very lucky, the scroll broken, nothing changed!'
</code></pre>


# 📚Apply Item Example - Attribute Scroll

{% hint style="info" %}
This example file will only work for <mark style="color:red;">**PREMIUM**</mark> version of **MythicChanger**.
{% endhint %}

<pre class="language-yaml"><code class="lang-yaml"><strong># Display Item
</strong><strong>display-item:
</strong>  material: PAPER
  name: '&#x26;#da8f87Attribute Scroll &#x26;7(Attack Damage &#x26;a+0.5&#x26;7)'
  lore:
    - '&#x26;8Scroll'
    - ''
    - '&#x26;7Drag any &#x26;cswords or axes &#x26;7onto this item to'
    - '&#x26;7make its &#x26;bAttack Damage &#x26;7value &#x26;a+0.5&#x26;7.'
    - '&#x26;7Up to value &#x26;410&#x26;7 can be upgraded.'
    - ''
    - '&#x26;bSuccess Rate: &#x26;a50%'
    - '&#x26;a&#x26;lRare'
  max-stack: 1
  
# Chance, Up to 100
chance: 50
  
# Rule Configs
real-changes:
  add-attributes:
    ATTACK_DAMAGE: 
      name: attack_damage 
      amount: '0.5'
      operation: ADD_NUMBER 
      slot: HAND 

# Match Item
match-item:
  material-tag:
    - swords

# Conditions
conditions:
  1:
    type: placeholder
    rule: '&#x3C;'
    placeholder: '{item_attributes.ATTACK_DAMAGE.amount;;0}'
    value: 10
    
# Actions
success-actions:
  1:
    type: message
    message: '&#x26;fCool, it looks like magic is showing off, your {name} &#x26;fis more powerful now!'
fail-actions:
  1:
    type: message
    message: '&#x26;fOh, no! Seems that this time you are now very lucky, the scroll broken, nothing changed!'
</code></pre>


# 📚Apply Item Example - Stat Scroll

{% hint style="info" %}
This example file will only work for <mark style="color:red;">**PREMIUM**</mark> version of **MythicChanger**.

You <mark style="color:red;">**NEED**</mark> install **NBTAPI** plugin first.
{% endhint %}

```yaml
# Display Item
display-item:
  material: PAPER
  name: '&#da8f87Stat Scroll &7(Attack Damage &a+10%&7)'
  lore:
    - '&8Scroll'
    - ''
    - '&7Drag any &cswords or axes &7onto this item to'
    - '&7make its &bAttack Damage &7value &a+10%&7.'
    - '&7Up to value &420&7 can be upgraded.'
    - ''
    - '&bSuccess Rate: &a100%'
    - '&a&lRare'
  max-stack: 1
  
# Chance, Up to 100
chance: 100
  
# Rule Configs
real-changes:
  add-name-last: '&6★'
  add-nbt-double:
    - 'MMOITEMS_ATTACK_DAMAGE;;{nbt_MMOITEMS_ATTACK_DAMAGE;;1}*1.1'
  remove-nbt:
    - 'HSTRY_ATTACK_DAMAGE'
  mi-update-lore: true

# Match Item
match-item:
  items:
    - 'YourMMOItemsSwordID'
  not:
    contains-name: 
      - '&6★&6★&6★&6★&6★'

# Conditions
conditions:
  1:
    type: placeholder
    rule: '<'
    placeholder: '{nbt_MMOITEMS_ATTACK_DAMAGE;;1}'
    value: 18.18
    
# Actions
success-actions:
  1:
    type: message
    message: '&fCool, it looks like magic is showing off, your {name} &fis more powerful now!'
fail-actions:
  1:
    type: message
    message: '&fOh, no! Seems that this time you are now very lucky, the scroll broken, nothing changed!'
```


# 📚Apply Item Example - Stat Scroll with Usage Times Limit

{% hint style="info" %}
You <mark style="color:red;">**NEED**</mark> install **NBTAPI** plugin first.
{% endhint %}

```yaml
# Display Item
display-item:
  material: PAPER
  name: '&#da8f87Stat Scroll &7(Armor &a+10%&7)'
  lore:
    - '&8Scroll'
    - ''
    - '&7Drag any &carmor &7onto this item to'
    - '&7make its &bArmor &7value &a+10%&7.'
    - '&7Up to upgrade &420&7 times.'
    - ''
    - '&bSuccess Rate: &a100%'
    - '&a&lRare'
  max-stack: 1
  
# Chance, Up to 100
chance: 100
  
# Rule Configs
real-changes:
  add-name-last: '&6★'
  add-nbt-double:
    - 'MMOITEMS_ARMOR;;{nbt_MMOITEMS_ARMOR;;1}*1.1'
    - 'UPGRADE_TIMES;;{nbt_UPGRADE_TIMES;;0}+1' # Log the useage times
  remove-nbt:
    - 'HSTRY_ARMOR'
  mi-update-lore: true

# Match Item
match-item:
  items:
    - 'YourMMOItemsArmorID'

# Conditions
conditions:
  1:
    type: placeholder
    rule: '<='
    placeholder: '{nbt_UPGRADE_TIMES;;0}'
    value: 20 # Set the maxmium use times here.
    
# Actions
success-actions:
  1:
    type: message
    message: '&fCool, it looks like magic is showing off, your {name} &fis more powerful now!'
fail-actions:
  1:
    type: message
    message: '&fOh, no! Seems that this time you are now very lucky, the scroll broken, nothing changed!'
```


# 📚Apply Item Example - Lucky or Bad Scroll

{% hint style="info" %}
This example file will only work for <mark style="color:red;">**PREMIUM**</mark> version of **MythicChanger**.
{% endhint %}

```yaml
# PREMIUM VERSION ONLY

# Display Item
display-item:
  material: PAPER
  name: '&#da8f87Luck or Bad Scroll'
  lore:
    - '&8Scroll'
    - ''
    - '&d✦ &#cbccc2Drag &cdiamond sword or golden sword &#cbccc2onto this item to'
    - '&7add enchantment for it.'
    - '&c■ &#cbccc2Has &#e957ca9%&#cbccc2 chance failed.'
    - '&c■ &#cbccc2Has &#e957ca1%&#cbccc2 chance break your sword.'
    - ''
    - '&#d9afd9Be careful!'
    - '&a&lRare'
  max-stack: 1

chance: 100

# Rule Configs
real-changes:
  sub-change:
    1:
      match-item:
        material:
          - diamond_sword
      changes:
        random-change:
          1:
            add-enchants:
              knockback: 1
            actions:
              1:
                type: message
                message: '&d✦ &fCool, the enchantment added!'
            rate: 3
          2:
            empty: true
            actions:
              1:
                type: message
                message: '&c☹ Bad, nothing happened!'
            rate: 9
          3:
            set-amount: 0
            actions:
              1:
                type: message
                message: '&c☹ Too bad, the item even disappear!'
            rate: 1
    2:
      match-item:
        material:
          - golden_sword
      changes:
        random-change:
          1:
            add-enchants:
              unbreaking: 1
            actions:
              1:
                type: message
                message: '&d✦ &fCool, the enchantment added!'
            rate: 90
          2:
            empty: true
            actions:
              1:
                type: message
                message: '&c☹ Bad, nothing happened!'
            rate: 9
          3:
            set-amount: 0
            actions:
              1:
                type: message
                message: '&c☹ Too bad, the item even disappear!'
            rate: 1

# Match Item
match-item:
  material-tag:
    - 'swords'
```


# 📚Apply Item Example - Item Skin Scroll

{% hint style="info" %}
This example file will only work for <mark style="color:red;">**PREMIUM**</mark> version of **MythicChanger**.
{% endhint %}

{% code title="item\_skin.yml" %}

```yaml
# PREMIUM VERSION ONLY

apply-item-mode: GENERAL

# Display Item
display-item:
  material: PAPER
  name: '&fItem Skin &8(Diamond Sword)'
  lore:
    - '&7Drag this item onto the item you want to apply.'
  max-stack: 1

# Rule Configs
real-changes:
  edit-item:
    custom-model-data: 15
  add-nbt-int:
    - 'original_custom_model_data;;{item_custom-model-data;;-1}'
  add-nbt-string:
    - 'used_skin_id;;item_skin'

# Match Item
match-item:
  item-format:
    material: diamond_sword
  item-format-settings:
    require-same-key: false
  not-match-actions:
    1:
      type: message
      message: '&c☹ &fYour sword type is not diamond sword!'

# Conditions
conditions:
  1:
    type: placeholder
    placeholder: '{nbt_used_skin_id;;0}'
    rule: '=='
    value: '0'
    not-meet-actions:
      1:
        type: message
        message: '&c☹ &fThis item already includes item skin!'

# Actions
success-actions:
  1:
    type: message
    message: '&d✦ &fCool, it looks like magic is showing off, your {name} &fhas skin now!'
```

{% endcode %}

{% code title="item\_skin\_rollback.yml" %}

```yaml
# PREMIUM VERSION ONLY

apply-item-mode: GENERAL

# Display Item
display-item:
  material: PAPER
  name: '&fItem Skin Rollback &8(Diamond Sword)'
  lore:
    - '&7Drag this item onto the item have skin to rollback.'
  max-stack: 1

# Rule Configs
real-changes:
  sub-change-match-one: true
  sub-change:
    1:
      conditions:
        1:
          type: placeholder
          placeholder: '{nbt_original_custom_model_data;;-1}'
          rule: '<'
          value: 0
      changes:
        remove-custom-model-data: true
        remove-nbt:
          - 'original_custom_model_data'
          - 'used_skin_id'
    2:
      conditions:
        1:
          type: placeholder
          placeholder: '{nbt_original_custom_model_data;;-1}'
          rule: '>='
          value: 0
      changes:
        set-custom-model-data: '{nbt_original_custom_model_data;;-1}'
        remove-nbt:
          - 'original_custom_model_data'
          - 'used_skin_id'

# Match Item
match-item:
  item-format:
    material: diamond_sword
  item-format-settings:
    require-same-key: false
  contains-nbt:
    - 'original_custom_model_data'
  not-match-actions:
    1:
      type: message
      message: '&c☹ &fThis sword does not include valid skin!'

# Actions
success-actions:
  1:
    type: message
    message: '&d✦ &fCool, it looks like magic is showing off, your {name} &fis rollback!'
  # Give back the skin item.
  2:
    type: console_command
    command: 'mc giveapplyitem {nbt_used_skin_id} {player}'
```

{% endcode %}


# Not Match Actions - Premium

You can add `not-match-actions` in `match-item` section, like this:

```yaml
match-item:
  has-name: false
  not-match-actions:
    1:
      type: message
      message: 'Your item already has name, it can not be changed!'
```

Should follow Action Format, for more info, please view [Format](/format/action-format) page.


# None

## None

No item will match, very useful for apply items.

```yaml
match-item:
  none: true
```


# Items

{% hint style="info" %}
It is recommend that you use [material](/match-item-rules/material) or [item-format](/match-item-rules/item-format) match rule instead, this rule is not very good for use.
{% endhint %}

## Items

Match by external plugin item ID.

```yaml
match-item:
  # Type item ID here, support third item plugins item ID.
  items:
    - 'diamond_sword'
    - 'superior_sword'
  use-tier-identify: true
```

{% hint style="info" %}
Type item ID or material ID **only**, no item type.

For MMOItems: Please note that the item ID needs to be capitalized.

For ItemsAdder: Namespace is required, like `namespace_test:item_id_here`.
{% endhint %}

## Use tier identify

For MMOItems and EcoItems plugin, there is also a `use-tier-identity` option available, which represents whether to use item ID or item tier. If changed to true, you can use tier IDs such as **RARE** here instead of the previous item ID.


# Material

## Material&#x20;

Match by material key (namespace key, case-insensitive).

Require item material must be the value of this list. This is very similar to items rule, but this rule will only use vanilla item material type.

```yaml
match-item:
  material:
    - 'diamond'
    - 'diamond_sword'
```


# Material Tag

## Material Tag <mark style="color:red;">- Premium</mark>

Match by vanilla item/block tag.

```yaml
match-item:
  material-tag:
    - 'swords'
```


# Contains Name/Contains Lore

{% hint style="info" %}
You shoud not put color code here if you enabled `ignore-color-code` option at `config.yml` file.
{% endhint %}

## Contains Name

Item display name must contain any listed text.

```yaml
match-item:
  contains-name:
    - 'test1'
```

## Contains Lore

Any lore line containing listed text will pass.

```yaml
match-item:
  contains-lore:
    - 'test1'
```


# Contains Enchants/Stored Enchants

{% hint style="info" %}
The `contains-enchants` rule itself already support stored enchants in enchanted book, so you don't need change the rule ID to `contains-stored-enchants`.
{% endhint %}

## Contains Enchants/Stored Enchants <mark style="color:red;">- Premium</mark>

Similar to `has-enchants`, but require the enchantment level must be greater than the value you set.

```yaml
match-item:
  contains-enchants:
    POWER: 1
```

## Contains specified levels enchants/stored Enchants <mark style="color:red;">- Premium</mark> <a href="#remove-enchants" id="remove-enchants"></a>

If you want to make only specified enchantment level take effect, you can use int list at here. For example, I want to make only item has Power level 1 enchantment match, then you should set this section like this:

```yaml
match-item:
  contains-enchants:
    POWER: [1] 
    OTHER: [1,2,5] # Means level1, 2 and 5.
```


# Contains Enchants/Stored Enchants Amount

## Min Enchants Amount <mark style="color:red;">- Premium</mark>

Check enchantment count.

The item must has at least 5 enchantments in this example.

```yaml
match-item:
  contains-enchants-amount: 5
```

## Contains Enchants Amount <mark style="color:red;">- Premium</mark>

Check enchantment count list.

This means item must has 3 or 5 enchantments in this example, if the item has 4 enchantments or other number of enchantments, it will not being matched.

```yaml
match-item:
  contains-enchants-amount: [3, 5]
```


# Contains Apply

## Contains Apply <mark style="color:red;">- Premium</mark>

Whether this item has been used specified [apply item](/drag-gui-change/apply-item). Only support apply item that includes fake changes.

```yaml
match-item:
  contains-apply:
    - 'A'
    - 'B'
```


# Contains NBT

## Contains NBT <mark style="color:red;">- Premium</mark>

Require NBTAPI, download it [here](https://www.spigotmc.org/resources/nbt-api.7939/).

Use `;;` distinguish key value hierarchy.&#x20;

```yaml
match-item:
  contains-nbt: 
    - 'PublicBukkitValues;;mythicchanger:apply_item_id'
```


# Has Name

## Has name

Whether only items with custom display names will match.

```yaml
match-item:
  has-name: true
```


# Has Lore

## Has lore

Whether only items with lores will match.

```yaml
match-item:
  has-lore: true
```


# Has Enchants

## Has Any Enchants <mark style="color:red;">- Premium</mark>

Require the item to has any enchantment.

```yaml
match-item:
  has-enchants:
    - '*'
```

## Has Enchants

Require the item to contain any listed enchantment.

```yaml
match-item:
  has-enchants:
    - 'POWER'
```

## Has Stored Enchants

For enchanted books, require stored enchantments.

* only valid for stored-enchant metadata
* `*` means any stored enchantment

```yaml
match-item:
  has-stored-enchants:
    - 'POWER'
```


# Has Apply

## Has Apply <mark style="color:red;">- Premium</mark>

Whether this item has been used any [apply item](/drag-gui-change/apply-item). Only support apply item that includes fake changes.

```yaml
match-item:
  has-apply: true
```


# Rarity

## Rarity (1.20.5+) <mark style="color:red;">- Premium</mark>

Require item must have specified rarity. Rarity require you extra set in item, by default all items don't have rarity, for item don't have custom rarity, plugin will use "NONE" as result.

{% hint style="info" %}
This is just mean vanilla item's ratity, if you mean ratity/tier from custom plugins, please view [this page](/match-item-rules/items).
{% endhint %}

```yaml
match-item:
  rarity: NONE
```


# NBT

## NBT String <mark style="color:red;">- Premium</mark>

Require NBTAPI, download it [here](https://www.spigotmc.org/resources/nbt-api.7939/).

Require specifed NBT type must be STRING.

Use `;;` distinguish key value hierarchy.&#x20;

The value after the last `;;` symbol represents the required NBT value.

```yaml
match-item:
  # Require this NBT value to be A.
  nbt-string:
    - 'PublicBukkitValues;;mythicchanger:apply_item_id;;A'
```

## NBT Int/NBT Double/NBT Byte <mark style="color:red;">- Premium</mark>

Require NBTAPI, download it [here](https://www.spigotmc.org/resources/nbt-api.7939/).

Similar to NBT String, but should has comparison symbols.

Comparsion symbols support:

* \>=
* <=
* \>
* <
* \==

```yaml
match-item:
  nbt-double:
    - 'PublicBukkitValues;;mythicchanger:test;;>=;;5'
```


# NOT

## NOT

If item didn't meet the match rule you set in NOT section, we will consider this rule as meet the rule.

**Never use this with replace-item change rule!**

```yaml
match-item:
  not:
    items:
      - 'diamond_sword'
```


# ANY

## ANY <mark style="color:red;">- Premium</mark>

If item meet any of those match item rules, we will consider it meet the rule.

```yaml
match-item:
  any:
    rarity: COMMON
    material:
      - 'diamond'
```

## ANY Of <mark style="color:red;">- Premium</mark>

```yaml
match-item:
  any:
    1: 
      contains-name:
        - 'Hello'
      contains-lore:
        - 'Oh'
    2:
      contains-lore:
        - 'What'
```


# Enchantable

## Enchantable <mark style="color:red;">- Premium</mark>

This item can be enchanted by any of those enchantments.

```yaml
match-item:
  enchantable:
    - respiration
```


# Item Format

## Item Format

Require item's item format specifed key's value must same as the value set here.

```yaml
match-item:
  item-format:
    material: ENCHANTED_BOOK
    stored-enchants:
      bane_of_arthropods: 5
  item-format-settings:
    require-same-key: false
    ignore-key:
      - 'amount'
```

You can hold the item and use command `/mc generateitemformat` to generate item format at **the plugin (plugins/MythicChanger)** folder.

Options for `item-format-settings`:

* require-same-key: This means that the items set here must have all the data of the items owned by the player.
* ignore-key: The list of ItemFormat™ Key that will be ignored when check whether items are same.


# ⚠️Note

You can use **ALL** change rules at both `fake-changes` and `real-changes` option except we told you can not do that in some specific rules.&#x20;

You need use [mi-update-lore](/change-rules/mmoitems) rule after you modify **MMOItems**'s nbt data.

The rule name end with an `*` symbol indicates that the item will be replaced after change, the original item will disappear, and then the new item will replace the original item. The data of the original item will be lost. You can consider using rules starting with `keep` to convert some of the data from the original item to the new item (this will cause some additional performance consumption). For more info, please view [here](/change-rules/keep).

When using **SubChange** and **RandomChange** rules, if a rule that requires a Replace Item is used, the parent rule will also be automatically considered as requiring a Replace Item.

<mark style="color:red;">**When using those rules, please be sure to note that the replaced item after the change should no longer meet this rule again, otherwise the item will be constantly replaced, causing a dead loop and ultimately causing the server to crash!**</mark><mark style="color:red;">**&#x20;**</mark>*<mark style="color:red;">**REMEMBER THIS!**</mark>*

```yaml
fake-changes:
  add-name-first: '&fGood '
  set-name: '&fGood Diamond Sword'
  add-lore-last:
    - '&f&lCommon'
  set-lore:
    - '&7A good sword that all adventures should use!'
    - '&f&lCommon'
  add-lore-prefix: '%img_tooltip1%'
  set-custom-model-data: 5
  add-flags:
    - 'HIDE_ENCHANTS'

real-changes:
  add-enchants:
    POWER: 1
  remove-enchants:
    - 'POWER'
  remove-all-enchants: true
  replace-item:
    material: golden_sword
```


# Empty

## Empty <a href="#add-name-first-add-name-last" id="add-name-first-add-name-last"></a>

Nothing changed.

```yaml
fake-changes:
  empty: ''
```


# Fix Hide Attributes

## Fix Hide Attributes

Hide Attribute item flag has bug in 1.20.6 higher version, this rule can try fix the items that the hide attribute flag does not work in some items.

```yaml
fake-changes:
  fix-hide-attributes: true
```


# Add Name

## Add name first/Add name last <a href="#add-name-first-add-name-last" id="add-name-first-add-name-last"></a>

Add new content to the left or right of the custom display name of the item.

{% hint style="info" %}
If you are getting name dupe, that is simply because your item name has actually changed in both server and client which it shouldn't be.\
\
You use **MythicChanger** to add`XX` at the start or end of the item name. After changing the name, if the real name of the item will change, and the changed item will still meet **MythicChanger**'s matching condition, MythicChanger will keep adding XX at the start or end of the item name.\
\
To solve this, you should manually add a `contains-name` matching rule to avoid **MythicChanger** keep modifiying item, also the name will not be able to update by us anymore.\
\
The real change don't always happen, only your other plugins or anvil can do that! Ban anvil rename item name is best choice.\
\
Many people use this rule for Custom Tooltips, what I want to say is: Why you don't use Lore's first line to cover the name of the item, because this not only solves the problem of players being able to modify Tooltips in the anvil, but also solves the problem of seeing Tooltips when switching items in the shortcut bar.
{% endhint %}

```yaml
fake-changes:
  add-name-first: '&fGood '
  add-name-last: ' &d(New)'
```


# Add Lore

## Add lore first/Add lore last <a href="#add-lore-first-add-lore-last" id="add-lore-first-add-lore-last"></a>

Add content at the beginning or end of the item Lore.

```yaml
fake-changes:
  add-lore-first:
    - '&7A very very old sword!'
  add-lore-last:
    - '&f&lCommon'
```

Adding content before or after each line in Lore and this is very useful for users who want to add a Tooltip icon.

```yaml
fake-changes:
  add-lore-prefix: '%img_tooltip1%'
  add-lore-suffix: 'This is end of the line'
```


# Add Attributes

## Add Attributes

```yaml
real-changes:
  add-attributes:
    ATTACK_DAMAGE: 
      name: attack_damage 
      amount: '{item_attributes.ATTACK_DAMAGE.amount;;0} + 1'
      operation: ADD_NUMBER 
      slot: HAND # Optional, if not set, plugin will auto set by material type
```


# Add Tool

## Add Tool - 1.21+

`add-tool` is used to modify an item's vanilla **Tool Data Component**, allowing normal items or tools to behave with specified mining speed, durability consumption, and block-breaking rules on both the client and server.

### Basic Format

```yaml
real-changes:
  add-tool:
    mining-speed-multiplier: 1.5
    damage-per-block-add: 1
    rules:
      - 'minecraft:stone,2.0,true'
```

### Available Options

#### `mining-speed-multiplier`

Sets the default mining speed multiplier.

The value is calculated based on the item's current default mining speed from its existing Tool Component.

```yaml
add-tool:
  mining-speed-multiplier: 1.75
```

The old option name `mining-speed` is also supported and has the same effect as `mining-speed-multiplier`.

```yaml
add-tool:
  mining-speed: 1.75
```

#### `damage-per-block`

Directly sets the durability consumed each time a block is broken.

```yaml
add-tool:
  damage-per-block: 2
```

#### `damage-per-block-add`

Adds the specified value to the current durability consumption.

The final value will not be lower than `0`.

```yaml
add-tool:
  damage-per-block-add: 1
```

#### `rules`

Adds tool rules for specific blocks.

Format:

```yaml
rules:
  - 'Block ID,Mining Speed Multiplier,Correct For Drops'
```

Example:

```yaml
add-tool:
  rules:
    - 'minecraft:stone,2.5,true'
    - 'minecraft:oak_log,2.25,true'
```

You can also define multiple blocks in the same rule:

```yaml
add-tool:
  rules:
    - 'minecraft:stone,minecraft:deepslate,2.0,true'
```

The last two parameters are always:

```yaml
Mining Speed Multiplier,Correct For Drops
```

`Correct For Drops` can be:

| Value   | Description                                                                                |
| ------- | ------------------------------------------------------------------------------------------ |
| `true`  | This tool is considered the correct tool for breaking these blocks, allowing normal drops. |
| `false` | This tool is not considered the correct tool.                                              |
| `null`  | Does not override the vanilla judgment.                                                    |

### Full Example

```yaml
real-changes:
  add-lore-last:
    - '&7Affix: &aQuarry Heart'
  add-attributes:
    block_break_speed:
      name: 'mythicchanger:tool_quarry_heart'
      amount: 1.6
      operation: ADD_NUMBER
      slot: HAND
  add-tool:
    mining-speed-multiplier: 1.75
    damage-per-block-add: 1
    rules:
      - 'minecraft:stone,2.5,true'
      - 'minecraft:deepslate,2.0,true'
```

### Effect Explanation

The configuration above will make the item:

* Gain additional lore.
* Gain an extra `block_break_speed` attribute.
* Increase its default mining speed to `1.75x` of the original value.
* Consume 1 additional durability point each time a block is broken.
* Use `2.5x` mining speed for `stone` and treat it as the correct tool.
* Use `2.0x` mining speed for `deepslate` and treat it as the correct tool.

### Notes

* `add-tool` only works on **Minecraft 1.21+**.
* If the item does not already have a suitable Tool Component, it is recommended to use this feature mainly on vanilla tool items such as pickaxes, axes, shovels, hoes, shears, and brushes.
* If you only want to display information without actually changing tool behavior, use lore-related rules under `fake-changes`.
* If you want to actually change mining behavior, use `add-tool` under `real-changes`.


# Set Name/Lore

## Set name/Set Lore <a href="#set-name-set-lore" id="set-name-set-lore"></a>

Set custom display names or lore for items.&#x20;

{% hint style="info" %}
Please note: The placeholder `{name}` will includes item name's color code, which means you set set-name: `'&6{name}'` won't work because item itself will override the color code you set before. You need use `{raw-name}` instead, this placeholder will return the value don't include color code. This placeholder only available in <mark style="color:red;">**PREMIUM**</mark> version.
{% endhint %}

```yaml
fake-changes:
  set-name: '&fGood {name}' # Supported placeholder: {name}
  set-lore:
    - '&7A good sword that all adventures should use!'
    - '&f&lCommon'
```


# Set/Remove Custom Model Data

## Set Custom Model Data <a href="#set-custom-model-data" id="set-custom-model-data"></a>

Setting the Custom Model Data for an item.

```yaml
fake-changes:
  set-custom-model-data: 5
```

## Remove Custom Model Data

```yaml
fake-changes:
  remove-custom-model-data: true
```


# Set/Remove Item Model

## Set Item Data <a href="#set-custom-model-data" id="set-custom-model-data"></a>

Setting the Item Data for an item.

```yaml
fake-changes:
  set-item-model: 'mycustom:test'
```

## Remove Item Data

```yaml
fake-changes:
  remove-item-model: true
```


# Set Amount/Disappear

## Set Amount <a href="#add-flag-remove-flag" id="add-flag-remove-flag"></a>

Supported placeholder:&#x20;

* {amount} - Now item amount, don't use it in fake changes.
* {max-stack} - Get this material max stack size, for example diamond's max stack size is 64.

```yaml
real-changes:
  set-amount: 5 
```

## Disappear

Just try set item amount to 0.

```yaml
real-changes:
  set-amount: 0
```


# Add flag/Remove flag

## Add flag/Remove flag <a href="#add-flag-remove-flag" id="add-flag-remove-flag"></a>

Flag ID list:

<https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/inventory/ItemFlag.html>

```yaml
fake-changes:
  add-flags:
    - 'HIDE_ENCHANTS'
  remove-flags:
    - 'HIDE_DYE'
```


# Add enchants

## Add enchants <a href="#add-enchants" id="add-enchants"></a>

Add enchantments to items. Please note that in general, you should use it in `real-changes`. If you use it in `fake-changes`, the enchantment will actually take effect, but it appears to disappear.

```yaml
real-changes:
  add-enchants:
    POWER: 1
  add-enchants-ignore-level: true # If set to false, and the item already has this enchantment, we will check the enchantment level item has, if greater than the value you set here, we will skip this rule.
```

## Add stored enchants

```yaml
real-changes:
  add-stored-enchants:
    POWER: 1
  add-stored-enchants-ignore-level: true # If set to false, and the item already has this enchantment, we will check the enchantment level item has, if greater than the value you set here, we will skip this rule.
```


# Delete enchants

## Delete enchants <a href="#delete-enchants" id="delete-enchants"></a>

Delete the enchantment on the item, please note that the number after the enchantment represents the effective value. If the enchantment level of an item is greater than this value (excluding this value), the enchantment will be deleted.

In this example, items with Knockback I enchantment will not be affected, while items with Knockback II enchantment will be deleted.

```yaml
real-changes:
  delete-enchants:
    KNOCKBACK: 1
```

If you want to make only specified enchantment level take effect, you can use int list at here. For example, I want to make only item has Knockback level 1 enchantment match, then you should set this section like this:

```yaml
real-changes:
  delete-enchants:
    KNOCKBACK: [1] # Added = symbol before the value.
    OTHERS: [1,2,5] # Means level1, 2 and 5.
```

## Delete stored enchants

```yaml
real-changes:
  delete-stored-enchants:
    KNOCKBACK: 1
```

```yaml
real-changes:
  delete-stored-enchants:
    KNOCKBACK: [1] # Added = symbol before the value.
    OTHERS: [1,2,5] # Means level1, 2 and 5.
```


# Remove Name/Lore

## Remove Name

```yaml
real-changes: 
  remove-name: true
```

## Remove All Lore

```yaml
real-changes:
  remove-all-lore: true
```


# Remove Enchants

## Remove Enchants <a href="#remove-enchants" id="remove-enchants"></a>

Similar to `delete-enchants` but ignore the enchantment levels.

```yaml
real-changes:
  remove-enchants:
    - 'KNOCKBACK'
```

## Remove all enchantments <a href="#remove-all-enchantments" id="remove-all-enchantments"></a>

```yaml
real-changes:
  remove-all-enchants: true
```

## Remove Stored Enchants <a href="#remove-enchants" id="remove-enchants"></a>

Similar to `delete-stored-enchants` but ignore the enchantment levels.

```yaml
real-changes:
  remove-stored-enchants:
    - 'KNOCKBACK'
```

## Remove all enchantments <a href="#remove-all-enchantments" id="remove-all-enchantments"></a>

```yaml
real-changes:
  remove-all-stored-enchants: true
```


# Remove Attributes

## Remove Attribute

<pre class="language-yaml" data-title=""><code class="lang-yaml"><strong>real-changes:
</strong><strong>  remove-attributes:
</strong>    - armor
    - movement_speed
</code></pre>

## Remove Attribute By/Contains Name

{% code title="" %}

```yaml
real-changes:
  remove-attribute-by-name:
    - 'mythicchanger:armor_bulwark'

  remove-attribute-contains-name:
    - 'mythicchanger:armor_'
```

{% endcode %}


# Set Type

## Set Type <a href="#set-type" id="set-type"></a>

Set item's type to other material.

```yaml
real-changes:
  set-type: STONE
```


# Random

{% hint style="info" %}
Using random type rules for **fake change** is <mark style="color:red;">**meaningless**</mark> because it will cause the item to constantly change (because each time player interact item, we will start fake change). Suggest using them only in **real changes**.\
Even using in **real change**, you need make sure **after random change, the item after change should NOT match the same rule again** otherwise the item will still constantly change because it still match the rule and randomly changed.

Example:

```yaml
match-item:
  items:
    - 'diamond'
  has-lore: false # This match rule make sure after change, the item will no longer be random changed by this rule.

real-changes:
  random-change:
    1:
      set-lore: 
        - 'Lucky Boy' # After change, the item will has lore, so it will only be changed once, otherwise it will always be changed by this rule.
      rate: 5
    2:
      set-lore: 
        - 'Not Lucky Boy'
      rate: 15
```

{% endhint %}

## Random Replace Item\* <mark style="color:red;">- Premium</mark>

Use the ItemFormat [here](https://ultimateshop.superiormc.cn/base/item-format).

```yaml
real-changes:
  replace-random-item:
    1:
      # Put Item Format here.
      material: APPLE
      rate: 5
    2:
      # Put Item Format here.
      material: DIAMOND
      rate: 15
```

## Random Change <mark style="color:red;">- Premium</mark>

```yaml
real-changes:
  random-change:
    1:
      changes:
      # Put Change Rules here.
        set-lore: 
          - 'Lucky Boy'
      match-item: []
      rate: 5
      actions:
        1:
          type: message
          message: 'So lucky!'
    2:
      changes:
        set-lore: 
          - 'Not Lucky Boy'
      rate: 15
```


# Replace Item

## Replace item\* <a href="#replace-new-item" id="replace-new-item"></a>

Use the ItemFormat [here](https://ultimateshop.superiormc.cn/base/item-format).

You need use this both in `fake-changes` and `real-changes` option to make it working well.

{% hint style="info" %}
The data of the original item will be lost. You can consider using rules starting with `keep` to convert some of the data from the original item to the new item (this will cause some additional performance consumption). For more info, please view [here](/change-rules/keep).
{% endhint %}

```yaml
fake-changes:
  replace-item:
    # Put Item Format here.
    hook-plugin: MMOItems
    hook-item: 'MATERIAL;;REAR_INGOT'
real-changes:
  replace-item:
    # Put Item Format here.
    hook-plugin: MMOItems
    hook-item: 'MATERIAL;;REAR_INGOT'
```


# Replace Name

## Replace Name

```yaml
real-changes:
  replace-name:
    'Hello': 'Hello!'
```


# Replace Lore

## Replace Lore <a href="#replace-lore" id="replace-lore"></a>

Replace specific content to other value in item's lore. Support use \n means start a new line.

```yaml
fake-changes:
  replace-lore:
    'Click to': 'Click \nto'
```


# Replace Enchants

## Replace Enchants <mark style="color:red;">- PREMIUM</mark>

```yaml
real-changes:
  replace-enchants:
    knockback: power
```

## Replace Stored Enchants <mark style="color:red;">- PREMIUM</mark>

```yaml
real-changes:
  replace-stored-enchants:
    knockback: power
```


# Set/Remove Color

## Set Color

Set leather armor color to new color.

```yaml
fake-changes:
  set-color: 'ff0000'
```

## Remove Color

```yaml
fake-changes:
  remove-color: true
```


# Sub Change

## Sub Change <mark style="color:red;">- PREMIUM</mark>

Sometimes, you can continue to filter under the item you want to match, and this rule can help you achieve this.\
In this example, match item first helped you filter out all the swords, and in the sub change rule, we further divided the diamond sword and the golden sword into two different change rules.

```yaml
match-item:
  material-tag:
    - 'swords'

real-changes:
  # If set to true, item will only be changed once in sub change rule.
  sub-change-match-one: false
  sub-change:
    1:
      match-item:
        material:
          - diamond_sword
      changes:
        add-enchants:
          knockback: 1
      actions:
        1:
          type: message
          message: 'Cool!'
    2:
      match-item:
        material:
          - golden_sword
      changes:
        add-enchants:
          unbreaking: 1
```


# Parse PAPI

## Parse PAPI

Require PlaceholderAPI. Other change rule related to name and lore contains this feature, so you don't need use this rule twice.

Support `parse-papi-name` and `parse-papi-lore`.

```yaml
fake-changes:
  parse-papi-name: true
  parse-papi-lore: true
```


# NBT

## Add NBT\* <mark style="color:red;">- Premium</mark>

Require NBTAPI, download it [here](https://www.spigotmc.org/resources/nbt-api.7939/).

Support `add-nbt-string, add-nbt-int, add-nbt-double, add-nbt-byte` change rule.

Use `;;` distinguish key value hierarchy.&#x20;

The value after the last `;;` symbol represents the NBT value.

```yaml
real-changes:
  add-nbt-int:
    - 'test;;5'
  add-nbt-string:
    # Key;;Value
    - 'test;;t'
```

## Remove NBT\* <mark style="color:red;">- Premium</mark>

Require NBTAPI, download it [here](https://www.spigotmc.org/resources/nbt-api.7939/).

Use `;;` distinguish key value hierarchy.&#x20;

```yaml
real-changes:
  remove-nbt:
    - 'fff;;fff'
```


# Edit Item

## Edit Item

Edit the item by Item Format.

Some change rule can be done by Item Format, for example:

For set name rule:

```yaml
fake-changes:
  set-name: 'test1'
```

can be replaced to:

```yaml
fake-changes:
  edit-item:
    name: 'test1'
```

View Item Format [here](https://ultimateshop.superiormc.cn/base/item-format). You can parse hold item to ItemFormat by using `/mc generateitemformat` command.

## Edit Item and Replace\*

If you want to rewrite item, you can use `replace-item` option in this rule.

```yaml
fake-changes:
  edit-item:
    name: 'test1'
    repalce-item: true
```


# Edit Lore

## Edit Lore <mark style="color:red;">- Premium</mark>

Edit specifed line's lore. Format is `line number (or last to mean the last line): The modified lore text (support use {original} to mean the original lore line text)`.

```yaml
fake-changes:
  edit-lore:
    30: 'test'
    last: '&f{original} hello!'
  edit-lore-bypass: false
```

In this example, we set item's lore value to test in line 30, however, if this item don't have 30 lines, we will only try add new line for this item. If you don't want this and just want us ignore the exceeding line, please use `edit-lore-bypass option`.


# Keep

## Keep <mark style="color:red;">- Premium</mark>

If a rule with the `*` symbol is used, the original item will disappear and a new item will replace the original item. Therefore, the data of the original item will disappear. If you want to retain some information about the original item, you need to use the rules here.

Support `keep-enchants, keep-name, keep-lore, keep-item-name, keep-flag, keep-damage` change rule.

<pre class="language-yaml"><code class="lang-yaml">fake-changes:
  keep-enchants: true
<strong>  keep-name: true
</strong>  keep-lore: true
  keep-item-name: true
  keep-flag: true
  keep-damage: true
</code></pre>

{% hint style="warning" %}
Keep is a standard change rule, not a option inside ItemFormat, for example:

```yaml
fake-changes:
  keep-enchants: true
  replace-item:
    # keep-enchants: true <--- This is wrong! Put keep rules here will not work!
    hook-plugin: MMOItems
    hook-item: 'MATERIAL;;REAR_INGOT'
```

{% endhint %}

## Keep Item Format <mark style="color:red;">- Premium</mark>

You can copy the item format of the original item to a new item and enter the key value of the item format to be copied in this rule. For example:

```yaml
real-changes:
  keep-item-format:
    - 'enchants'
```

You can parse hold item to ItemFormat by using `/mc generateitemformat` command. You can distinguish the hierarchical relationship of YAML through the `.` symbol.&#x20;

```yaml
material: diamond_sword
enchants:
  sharpness: 1
  unbreaking: 2
```

In above example, if you just enter `'enchants'` in the rule, we will copy all content below enchants, you can also use `'enchants.sharpness'` if you just want to copy sharpness enchant. The `.` symbol between `'enchants'` and `'sharpness'` represents their hierarchical relationship.


# Deapply

## Deapply <mark style="color:red;">- Premium</mark>

Rollback the item to it's original one (only supports fake change), also remove it's apply item data so that this item can use another apply item.

```yaml
real-changes:
  deapply: true
```


# Apply Limit

## Add apply limit/Set apply limit/Reset apply limit <mark style="color:red;">- Premium</mark>

It doesn't mean a limit on the number of times an apply item is used, but a limit on the type of apply item. If you need to limit the maximum number of times an apply item can be used, you can flexibly set the match item based on the apply item. For example, this apply item can add a level to the item's enchantment each time. Then, when the item's enchantment level is greater than a certain value, it can be considered as using the apply item a certain number of times, or you can add a double type nbt to it every time you use the apply item. Add 1 to the value of this nbt every time it is used, and the final value stored in nbt is the number of times it has been used. For example of set limit of apply item use times, please view this [example file](/drag-gui-change/apply-item-example-stat-scroll-with-usage-times-limit).

```yaml
real-changes:
  add-apply-limit: 5
  set-apply-limit: 15
  reset-apply-limit: true
```


# Damage

## Add Damage

{% code title="" %}

```yml
real-changes:
  add-damage: 10
```

{% endcode %}

## Repair Damage

{% code title="" %}

```yml
real-changes:
  repair-damage: 10
```

{% endcode %}

## Damage Modify

This will directly modify item damage to 100.

{% code title="" %}

```yml
real-changes:
  damage: 100
```

{% endcode %}

Advanced format:

{% code title="" %}

```yml
real-changes:
  damage:
    operation: ADD
    value: 10
```

{% endcode %}

For operation option, supports value:

* SET
* ADD
* SUBTRACT
* MULTIPLY


# Conditions

Require PREMIUM version of MythicChanger.

Condition not means a match rule called condition, this page only tell you that you can also use Condition Fomrat to match the item you want in apply item configs! For example:

```yaml
# Match Item
match-item:
  items:
    - 'YourMMOItemsArmorID'

# Conditions
conditions:
  1:
    type: placeholder
    rule: '<='
    placeholder: '{nbt_UPGRADE_TIMES;;0}'
    value: 20 # Set the maxmium use times here.
```


# Remove/Reset Data - Require Paper

For list of available data type, please view: <https://jd.papermc.io/paper/26.1.2/io/papermc/paper/registry/keys/DataComponentTypeKeys.html>

## Remove Data

Remove the specified data type in item.

This also includes the most basic data values under vanilla items.

Maybe very hard to understand, right?

Let us take an example:

By default, diamond pickaxe contains a tool data that allows it to mine stones faster. If we delete it, the speed of diamond pickaxe mining stones will be the same as its empty hand speed.

```yaml
match-item:
  items:
    - 'diamond_pickaxe'
    
real-changes:
  remove-data:
    - 'tool'
```

## Reset Data

Unlike Remove Data, Reset Data only restores the data corresponding to the item to its default value, rather than completely deleting it.

```yaml
real-changes:
  reset-data:
    - 'tool'
```


# UltimateShop

## Add Price Lore

<figure><img src="https://2518436866-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FECy8m2ZXGWwelMAR2Swy%2Fuploads%2FBzahAvQq0ePgaqcR9ezl%2Fimage.png?alt=media&amp;token=291fce36-0440-436c-9c4d-0eb86fc77186" alt=""><figcaption></figcaption></figure>

<figure><img src="https://2518436866-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FECy8m2ZXGWwelMAR2Swy%2Fuploads%2FaWKE1IeASJOzhvh4Ujag%2F9b0906ace8ba0a265f6711301c6be2f7.png?alt=media&amp;token=fbd02092-04e1-4d2d-a73d-5045610eff63" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Requires UltimateShop **3.10.1+** version.
{% endhint %}

```yaml
weight: 15

only-in-player-inventory: true

fake-changes:
  add-price-lore:
    - '&fBuy Price: &6{buy-price} &7per unit'
    - '&fSell Price: &6{sell-price} &7per unit'
    - '&fWorth: &6{total-price}'
```


# EnchantmentSlots

## Set Slot <a href="#set-slot" id="set-slot"></a>

```yaml
real-changes:
  # Automatically calculate the slot of items
  es-set-slot: true
  # Manually set the slot
  es-set-slot: 5
```

## Add Slot <a href="#reset-slot" id="reset-slot"></a>

```yaml
real-changes:
  es-add-slot: -5
```

## Reset Slot <a href="#reset-slot" id="reset-slot"></a>

Reset means we will override the slot already exist in the item.

```yaml
real-changes:
  # Automatically calculate the slot of items
  es-reset-slot: true
  # Manually reset the slot
  es-reset-slot: 5
```

## Add Enchantment Slot Lore <a href="#add-enchantment-slot-lore" id="add-enchantment-slot-lore"></a>

```yaml
fake-changes: 
  es-add-lore: true
```

## Parse Item Placeholder from ES

For more info about Item Placeholder, please view [here](https://enchantmentslots.superiormc.cn/general-configs/built-in-placeholders).

```yaml
fake-changes: 
  es-parse-lore: true
```

## Remove Excess Enchantments

```yaml
real-changes:
  es-remove-excess-enchants: true
```

## Remove Enchantment Slot Lore

```yaml
real-changes:
  es-remove-lore: true
```

## Has Slot

Does the slot is more than specifed value?

```yaml
match-item:
  has-slot: 5
```


# MMOItems

{% hint style="warning" %}
This rule is not offical suppored by both MMOItems team and our team, as this part of codes is not offical public API from MMOItems, and MMOItems may change the logic all the time. I do not have patient to maintain all the time. Thanks.
{% endhint %}

## MMOItems Update Lore <mark style="color:red;">- Premium</mark>

```yaml
real-changes:
  mi-update-lore: true
```

This rule only work for real changes.&#x20;

This rule only support for items from MMOItems.

The Lore Update of MMOItems will also switch based on the NBT data values of history data, so it is advisable to remove all NBT data from history as well.

```yml
real-changes:
  add-nbt-double:
    - 'MMOITEMS_ATTACK_DAMAGE;;{nbt_MMOITEMS_ATTACK_DAMAGE;;1}*100'
  remove-nbt:
    - 'HSTRY_ATTACK_DAMAGE'
  mi-update-lore: true
```


# 🌏Advanced Language Managment

## Default Language

You can set default language at `config.yml` file.

```yaml
config-files:
  language: en_US
  # Premium version only.
  per-player-language: true
```

The input here is the name of the language file (without the suffix). All language files are stored in the "`languages`" folder. You can also create a new language file by simply copying the "`en_US.yml`" file and renaming it to the corresponding language code. For example, `zh_CN.yml`.

{% hint style="warning" %}
Content below was added in plugin version **3.0.4**.
{% endhint %}

## Per Player Language <mark style="color:red;">- Premium</mark>

You can enable `per-player-language` at `config.yml` file. After being enabled, the plugin will determine which language file to display to the player based on their client language. The server must have the relevant language files preloaded; otherwise, it will display content using the default language file.

Let us watch this video to understand it!

## Lang Placeholder

You can use `{lang:<langKey>}` placeholder in plugin message to enable players from all over the world to display language settings that match their client.

You can add your desired custom language text under the "`override-lang`" section of each language file, in the format of "`ID: text content`". For example:

```yaml
// ... The content originally present in the language file

# Added content
override-lang:
  # This means shop-title it's language key.
  shop-title: 'Item Shop'
```

```yaml
// ... The content originally present in the language file

# Added content
override-lang:
  # This means shop-title it's language key.
  shop-title: '物品商店'
```

Then use `{lang:shop-title}` in the place you want to use.

In `config.yml`, you can directly use `{lang}` to represent the custom language from the language file to be used. The language ID should be synchronized with the configuration file structure in the `config.yml` file, for example:

In `config.yml` file:

```yaml
placeholder:
  # Premium version only
  compare:
    up: '{lang}'
    down: '{lang}'
    same: '{lang}'
```

In each language file:

```yaml
// ... The content originally present in the language file

override-lang:
  placeholder:
    compare:
      up: '↑'
      down: '↓'
      same: '-'
```

Similarly, if we cannot find this custom language in the corresponding language file, we will search for it in the default language file. If it is still not found, then the plugin will not parse this placeholder.

## Advanced Message Format <mark style="color:red;">- Premium</mark>

The default language text is directly filled into the text content that needs to be output, along with [color codes](https://ultimateshop.superiormc.cn/features/color-code). However, you can also utilize this feature to enable the plugin to display not only regular chat box messages, but also actionbars, titles, bossbars, sounds, and more!

You can still use color codes (including MiniMessage) while using our advanced message format.

#### Common Usage

```yaml
welcome: 'Welcome to the server!'
```

#### Chat Message

```yaml
welcome: '[message]&aWelcome![/message]'
```

#### Title

<pre class="language-yaml"><code class="lang-yaml"><strong>welcome: '[title=20,60,20]&#x26;6Welcome;;&#x26;eThis is sub title[/title]'
</strong># Format: [title=fadeIn,Stay,fadeOut]title;;subTitle[/title]
</code></pre>

#### Both Chat Message and Title will be sent

You can mix and match these different message types, just like this.

```yaml
welcome: '[message]&aGood day![/message][title=20,60,20]&6Welcome;;&eThis is sub title[/title]'
```

#### Action Bar

```yaml
welcome: '[actionbar]&7Please wait...[/actionbar]'
```

#### Boss Bar - Early Alpha

```yaml
welcome: '[bossbar=GREEN,SOLID,1.0]&aHappy Today[/bossbar]'
```

#### Sound

```yaml
welcome: '[sound=ENTITY_EXPERIENCE_ORB_PICKUP,1,1][/sound][sound=ENTITY_PLAYER_LEVELUP,1,1][/sound]'
```


# 🎨Color Code

## Hex Color <a href="#hex-color" id="hex-color"></a>

To use hex color, you should use special color code, it should like this:

**\&#Hex color code**

For example, \&#ff0000.

## Gradient Color <a href="#gradient-color" id="gradient-color"></a>

To use gradient color, you should use special gradient color code, it should like this:

**&<#Start Color Code> Message &<#End Color Code>**

For example, &<#666666>UltimateShop &<#ffffff>


# ⚡Powerful Item Placeholders

## Where can I use them?

* In MythicChanger itself, you can use powerful item placeholders at fake or real changes's config. Like this:

```yaml
real-changes:
  add-enchants:
    sharpness: '{item_enchants.sharpness;;0} + 1'
```

* You can also use them at actions or conditions set in MythicChanger.
* Not all! You can use them at other item plugins that not packet based in lore! Just use `parse-papi-lore` change rule do it! Use this rule in fake changes only! Example rule file:

{% code title="plugins/MythicChanger/example\_placeholder.yml" %}

```yaml
match-item: []

fake-changes:
  parse-papi-name: true
  parse-papi-lore: true
```

{% endcode %}

## Placeholder List

* {name}
* {original-name} - The original item name, which means the item changed before.
* {raw-name} - The item name without color code. <mark style="color:red;">**(Premium)**</mark>
* {raw-original-name} - The original item name, but without any color code. <mark style="color:red;">**(Premium)**</mark>
* {amount}&#x20;
* {max-stack}
* {item\_\<Item Format Key>;;\<Default Value>} - Get the value of the item's specified Item Format value. You can use command `/mc generateitemformat` to view hold item's Item Format. <mark style="color:red;">**(Premium)**</mark>
* {nbt\_\<NBT Key>;;\<Default Value>} - Get the value of the item's specified Custom NBT value. You can use command `/mc viewnbt` to view hold item's Custom NBT. <mark style="color:red;">**(Premium, require NBTAPI)**</mark>
* ALL PLACEHOLDERAPI placeholders!

## Math

You can use placeholders and [Math Calculate Format](https://ultimateshop.superiormc.cn/format/math-calculate-format) in change configs! Just set `math.enabled` option to `true` in `config.yml` file and then enjoy!&#x20;


# 🌍Localized Item Name - Premium

## Requirements <a href="#requirements" id="requirements"></a>

* Server version 1.16+.

## Configs

* Open `config.yml` file, and fine below contents:

```yaml
config-files:
  generate-default-files: true
  language: en_US
  minecraft-locate-file:
    enabled: true
    generate-new-one: true
    file: 'zh_cn.json'
```

* Please set `minecraft-locate-file.enabled` option to true.
* Then also set `minecraft-locate-file.generate-new-one` option to true.
* Finally, set file option to your language locate file name. Support value:
  * af\_za.json
  * ar\_sa.json
  * ast\_es.json
  * az\_az.json
  * ba\_ru.json
  * bar.json
  * be\_by.json
  * bg\_bg.json
  * br\_fr.json
  * brb.json
  * bs\_ba.json
  * ca\_es.json
  * cs\_cz.json
  * cy\_gb.json
  * da\_dk.json
  * de\_at.json
  * de\_ch.json
  * de\_de.json
  * el\_gr.json
  * en\_au.json
  * en\_ca.json
  * en\_gb.json
  * en\_nz.json
  * en\_pt.json
  * en\_ud.json
  * enp.json
  * enws.json
  * eo\_uy.json
  * es\_ar.json
  * es\_cl.json
  * es\_ec.json
  * es\_es.json
  * es\_mx.json
  * es\_uy.json
  * es\_ve.json
  * esan.json
  * et\_ee.json
  * eu\_es.json
  * fa\_ir.json
  * fi\_fi.json
  * fil\_ph.json
  * fo\_fo.json
  * fr\_ca.json
  * fr\_fr.json
  * fra\_de.json
  * fur\_it.json
  * fy\_nl.json
  * ga\_ie.json
  * gd\_gb.json
  * gl\_es.json
  * haw\_us.json
  * he\_il.json
  * hi\_in.json
  * hr\_hr.json
  * hu\_hu.json
  * hy\_am.json
  * id\_id.json
  * ig\_ng.json
  * io\_en.json
  * is\_is.json
  * isv.json
  * it\_it.json
  * ja\_jp.json
  * jbo\_en.json
  * ka\_ge.json
  * kk\_kz.json
  * kn\_in.json
  * ko\_kr.json
  * ksh.json
  * kw\_gb.json
  * la\_la.json
  * lb\_lu.json
  * li\_li.json
  * lmo.json
  * lo\_la.json
  * lol\_us.json
  * lt\_lt.json
  * lv\_lv.json
  * lzh.json
  * mk\_mk.json
  * mn\_mn.json
  * ms\_my.json
  * mt\_mt.json
  * nah.json
  * nds\_de.json
  * nl\_be.json
  * nl\_nl.json
  * nn\_no.json
  * no\_no.json
  * oc\_fr.json
  * ovd.json
  * pl\_pl.json
  * pt\_br.json
  * pt\_pt.json
  * qya\_aa.json
  * ro\_ro.json
  * rpr.json
  * ru\_ru.json
  * ry\_ua.json
  * sah\_sah.json
  * se\_no.json
  * sk\_sk.json
  * sl\_si.json
  * so\_so.json
  * sq\_al.json
  * sr\_cs.json
  * sr\_sp.json
  * sv\_se.json
  * sxu.json
  * szl.json
  * ta\_in.json
  * th\_th.json
  * tl\_ph.json
  * tlh\_aa.json
  * tok.json
  * tr\_tr.json
  * tt\_ru.json
  * uk\_ua.json
  * val\_es.json
  * vi\_vn.json
  * vp\_vl.json
  * yi\_de.json
  * yo\_ng.json
  * zh\_hk.json
  * zh\_cn.json
  * zh\_tw\.json
  * zlm\_arab.json
* Like I put `zh_cn.json` here. Start the server, the plugin will say it starting download the file.
* If sucessfully download, you will say new localized item name, like me:

<figure><img src="https://2518436866-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FECy8m2ZXGWwelMAR2Swy%2Fuploads%2FTNwJUI2ayyUsqDwlx1Qo%2Fimage.png?alt=media&amp;token=d2487e3c-78fe-4c0a-abbe-16f65da58ec8" alt=""><figcaption></figcaption></figure>

## Problems

Do you have problems? Try:

* Delete the json file generated at `plugins/MythicChanger` folder then regenerate this file.
* Are you using premium version? Only premium version support this for now.
* Did plugin print error message when generate the locate file? If yes, try restart the server and plugin will auto regenerate.

## Note <a href="#note" id="note"></a>

* **After generate this file, please keep generate-new-one option to false.**
* **If your server upgraded game version, you need delete old locate file and regenerate new one.**
* Server or plugin maybe lag when **first time** open the shop menu after restart the server, because we need build a cache for those localized item name. Under normal circumstances, you should not feel it unless you have a lot of products.


# ✔️Only In Player Inventory

## Enable it in each rule

You can add `only-in-player-inventory` option in each rule to make this rule only apply to items in player inventory, all items outside player inventory won't be modified by MythicChanger.

Please note that this option only work for fake changes, for real change, it already be limited to player inventory, which means real changes itself never modify item outside player's inventory which is very danger.

## Check custom menu only

After enable this option, all slots outside player's inventory will not apply fake change, however, some people just want to hide our changes in custom menu plugins, so you can enable `check-chests-only` option in `config.yml`, after enable, crafting table, enchantment table and so on will still display our fake changes, only custom chest menu will be effected.


# 💾Saved Item (Item Manager) - Premium

## Create your item <a href="#create-your-item" id="create-your-item"></a>

You can create your own item at `items` folder of plugin, just create a **yml** file and then follow [ItemFormat](https://ultimateshop.superiormc.cn/format/itemformat-tm) in this file. The file name is the item ID.

## Save your item <a href="#save-your-item" id="save-your-item"></a>

You can use command `/mc saveitem <saveItemID> <saveItemMethod>` command to save your hold item. There are 2 methods to save item.

* Bukkit
  * If you are using Spigot version of UltimateShop: Use BukkitAPI's method to save item. The method only support saving vanilla data and persistent data stored through BukkitAPI, and other custom NBT data from other plugins will not be saved.
  * If you are using Paper version of UltimateShop: Use PaperAPI's method to save item, this new method can 100% save item data, no data will lose. **(Paper and 1.15+ server only)**
* ItemFormat: will parse item into [Item Format](https://ultimateshop.superiormc.cn/format/itemformat-tm).

An example for item config file that use Bukkit save item method with Paper version of MythicChanger:

```yaml
item: !!binary |-
  H4sIAAAAAAAA/21RzW4TMRCeJd0oWVB/1IIQXILEG/TGpSDxCKhXa2LPbkxsz8qepUlPPAonXoBn6nsw27TaViBZljzz/XmmAZjBy68oeE25eE4Ap3cLeOEdnEWfyGZs5ZPzGDm5GdSWhyQAMG+gsRx7TpSkNHA8gVtmRS7TINnLvSLUNTQFZcg4Fj7/Aqjg2GIyGG5wXwyhVJrj7SQScWeKoN2a4m9pNFw+9QicqdFqtRgj6QuOuoz7BRwJ7QQuvm18WenJhCHsV8lb+qCeHycFSnaDSaLGN13wevMPytk7qhp4819cmT2diVacT90YAhp4PTXsUISjSRhpSrcOAz2me/Vl1emMVuWGs1Pu+3+4kR0F43QrS5i3gVFKPRpd/dR7Ae8mwvdhS2vemT7gHteB4HzqsWzGnTp6th5hDjM4dRixI9NTNuvAdnvY0oWjFocgRvH6OVN6Inf1u22XUOchUHkY+vyeU+Bk0tXgiSo4s5wzWTEtZ+My96WqoT7o/Lm8VDr8BZMVpHJ0AgAA
```

An example for item config file that use ItemFormat save item method with Paper version of MythicChanger:

```yaml
material: DIAMOND
amount: 6
name: <blue>A good sword
lore:
- <gray>This is really nice!
custom-model-data: 1
max-stack: 6
food:
  nutrition: 5
  saturation: 5.0
tool:
  damage-per-block: 5
  mining-speed: 1.3
  rules:
  - STONE, 1.4, true
song: minecraft:otherside
glow: true
enchants:
  mending: 1
```

## Match Save Item&#x20;

Use `item-format` match rule and set `material` option in ItemFormat to the save item ID.

You can use saved item in [ItemFormat](https://ultimateshop.superiormc.cn/format/itemformat-tm). In ItemFormat, there is a option called `material`, by default, you need type vanilla item ID there, but, you can also use saved item id to let plugin directly get the saved item instead of generate a whole new item with that type.

```yaml
display-item:
  material: superior_sword # If saved item id is 'superior_sword'
```

Saved items will be cached in memory continuously after loading to avoid repeatedly reading the saved item file, which may consume too much server performance. However, the cost is that if you have too many saved items, it may correspondingly consume more memory.


# Add custom rules

Both match rule and change rule can be added by yourself with our API.

## Add as dependency <a href="#user-content-get-shop-object" id="user-content-get-shop-object"></a>

{% hint style="info" %}
As of January 17, 2026, the latest plugin version number is **3.0.7**. If this date is too far away, then you should check the latest plugin version number yourself, as the provided plugin version may be outdated or unavailable.
{% endhint %}

```xml
<repositories>
    <repository>
        <id>repo-lanink-cn</id>
        <url>https://repo.lanink.cn/repository/maven-public/</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>cn.superiormc.mythicchanger</groupId>
        <artifactId>plugin</artifactId>
        <version>[PLUGIN VERSION]</version>
        <scope>provided</scope>
    </dependency>
</dependencies>
```

```graphql
repositories {
    maven {
        url "https://repo.lanink.cn/repository/maven-public/"
    }
}

dependencies {
    compileOnly group: 'cn.superiormc.mythicchanger', name: 'plugin', version: '[PLUGIN VERSION]'
}

```

```kts
repositories {
    maven("https://repo.lanink.cn/repository/maven-public/")
}

dependencies {
    compileOnly("cn.superiormc.mythicchanger:plugin:[PLUGIN VERSION]")
}
```

## How to do that? <a href="#how-to-do-that" id="how-to-do-that"></a>

First you need creata a new class that extends AbstractChangesRule or AbstractMatchItemRule abstract class.

Then use:

```java
ChangesManager.changersManager.registerNewRule(AbstractChangesRule rule)
```

```java
MatchItemManager.matchItemManager.registerNewRule(AbstractMatchItemRule rule)
```

depends on that rule you want to register.

Both AbstractChangeRule and AbstractMatchItem object are abstract class.

## Want me help you add?

If you don't have any plugin development experience and want me to help you, first you need consider buy the premium version of MythicChanger.

If your wanted rule is universal (means many people also want use it) and does not very complex, I **MAYBE** consider add it.&#x20;


