> For the complete documentation index, see [llms.txt](https://frinn.gitbook.io/custom-machinery-1.19/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://frinn.gitbook.io/custom-machinery-1.19/recipes/upgrades.md).

# Upgrades

Machine upgrades are items that can be used to change the behaviors of a custom machine recipe while it's processing.

You can change the properties of almost every requirements, for example make a machine consume 2x more FE but also half the processing time.

You can define any item registered in the game as machine upgrade.

The defined item will works as a machine upgrade only if placed in an item component slot with `variant` property set to `upgrade`. See [Item Component](/custom-machinery-1.19/creating-custom-machines/machine-components/item-component.md) `variant` property for more info.

The machine upgrade must be defined in a json file placed in a datapack, such as machines and recipes json.

The path of the machine upgrade json file must be : `[datapack_name]/data/[namespace]/upgrades/my_upgrade.json` 

You can use whatever you want as \[datapack*name*] but \[namespace] and json file name must be all lowercase without spaces or special characters except *`_`*

### Properties

The upgrade json has 3 mandatory properties and 2 optional properties.

#### Mandatory properties

<details>

<summary>Item</summary>

#### Name : `item`

#### Description :&#x20;

The item you want to use as upgrade, you can define only one item per upgrade json file (but you can make as many file as you want).&#x20;

The item can be any vanilla or modded item.

#### Example :&#x20;

```json
"item": "minecraft:diamond"
```

The upgrade will be a vanilla diamond.

</details>

<details>

<summary>Machines</summary>

#### Name : `machines`

#### Description :&#x20;

A list of custom machines where this upgrade is allowed.

#### Example :&#x20;

```json
"machines": ["custommachinery:magic_spawner", "custommachinery:power_crusher"]
```

This upgrade can be applied to the magic spawner and power crusher machines.

</details>

<details>

<summary>Modifiers</summary>

#### Name : `modifiers`

#### Description :&#x20;

A list of [requirements modifiers](/custom-machinery-1.19/recipes/upgrades/modifiers.md). These are used to define how the upgrade will influence the recipe processing.

#### Example :

```json
"modifiers": [
    {
        "requirement": "custommachinery:energy",
	"mode": "input",
	"operation": "multiplication",
	"modifier": 0.5
    }
]
```

This modifier will half the energy input required to process the recipe. See more about requirement modifiers in the following section.

</details>

#### Optional properties

<details>

<summary>Max</summary>

#### Name : `max`

#### Description :&#x20;

A positive integer that define the maximum amount of upgrades of this type that can be applied in a machine at a time.

Each item in a stack count as a separate upgrade.

This does not limit the stack size in the upgrade slot, but upgrades in excess won't be taken in account.

#### Default : 64

#### Example :&#x20;

```json
"max": 4
```

Only 4 upgrades can be applied in the machine.

</details>

<details>

<summary>Tooltip</summary>

#### Name : `tooltip`

#### Description :&#x20;

The tooltip that will render when a player hover any machine upgrade item in a gui.\
This is a [text component](/custom-machinery-1.19/misc/text-component.md).

#### Default :&#x20;

```json
"tooltip": {
    "text": "custommachinery.upgrade.tooltip",
    "color": "aqua"
}
```

#### Example :&#x20;

```json
"tooltip": {
    "text": "Speed upgrade MK1",
    "color": "orange"
}
```

The tooltip will be "Speed upgrade MK1" in orange.

</details>

### Example

The machine upgrade json below make a vanilla diamond item half the recipe duration in the Custom Machinery Power Crusher included in the test datapack.

{% code title="upgrade.json" %}

```json
{
    "item": "minecraft:diamond",
    "machines": ["custommachinery:power_crusher"],
    "modifiers": [
        {
	    "requirement": "custommachinery:speed",
	    "mode": "input",
	    "operation": "multiplication",
	    "modifier": 0.5
	}
    ]
}
```

{% endcode %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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://frinn.gitbook.io/custom-machinery-1.19/recipes/upgrades.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.