# Custom Items

## Compatibility notes (for version <= 1.2.2)

The custom item feature is a major change to the plugin that introduces the support of custom items from 3rd-party plugins. **Please read this page carefully to minimize your loss of data and avoid other unexpected issues.**

**TL;DR:**

* Existing data is unaffected
* No upgrades are required
* **Breaking-changes** to the developer API (be careful if you are making addons!)

## Behind the system

The plugin is currently utilizing a super minimal approach to identify, store and obtain item:&#x20;

* A type of ore is basically the material name
* An ore (item) is a pair of material name and amount
* There is no additional item metadata!

The advantage is that it is super fast to identify and perform calculations, simple to implement internally and minimal for data storage.&#x20;

However, the disadvantage is that it cannot work with item meta. For a long time, the plugin has prevented the use of non-raw items such as ones having custom name, lore, enchantments, etc.

## Custom item support

All custom items have their own IDs. Using the ID is similar to using the vanilla material names.

For this, the plugin introduces **classifier** to distinct where an item come from:

* `ia` for ItemsAdder
* `ox` for Oraxen

The OreProcessor ID of an item:&#x20;

`OreProcessor ID = <classifier>:<ID from custom item plugin>`&#x20;

You might ask what about the ID format of vanilla items? Simply, just the whole string (no classifier)

| Example              | Explain                                                                                       |
| -------------------- | --------------------------------------------------------------------------------------------- |
| `iron_ingot`         | This denotes a vanilla item with material `iron_ingot`                                        |
| `ia:iasurvival:ruby` | This denotes an ItemsAdder item with ID `iasurvival:ruby` where `iasurvival` is the namespace |
| `ox:ruby`            | This denotes an Oraxen item with ID `ruby`                                                    |

**Note:** The term "ID" is **contextual**.&#x20;

* From the custom-item-plugin side, you do not need the classifer, for example, if you have ItemsAdder installed, can type `/ia give iasurvival:ruby` to obtain an item because that is an ItemsAdder command.
* From OreProcessor side, the classifier is required to distinct which provides such item. If it is vanilla, no classifier is needed.

## Usage

To add custom item, it is super simple, just prefix your item name with a classifier

```
coal # no classifer -> vanilla item whose material name is COAL
ox:custom_coal # ox classifier -> Oraxen item, with id is custom_coal
ia:mypack:coal # ia classifier -> ItemsAdder, with namespace and id is mypack:coal
```

Noticed that:

* Vanilla material names are case-insensitive
* For custom items, the ID are typically **case-sensitive**
* Some plugins might have namespace besides the ID

For example, this is how you allow custom items in the coal storage.

```yaml
# filter.yml
storage:
  coal: [coal, coal_ore, deepslate_coal_ore, coal_block, ia:mypack:coal]
```

To view the list of all items including the custom ones, you might use any command that having `item` parameter such as `/ore add`