# 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`


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://anhcraft.gitbook.io/oreprocessor/configuration/custom-items.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.