# 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](https://frinn.gitbook.io/custom-machinery-1.19/creating-custom-machines/machine-components/item-component) `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](https://frinn.gitbook.io/custom-machinery-1.19/recipes/upgrades/modifiers). 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](https://frinn.gitbook.io/custom-machinery-1.19/misc/text-component).

#### 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 %}