> For the complete documentation index, see [llms.txt](https://frinn.gitbook.io/custom-machinery-1.21/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.21/recipes/upgrades.md).

# Upgrades

Machine upgrades are items that can be used to change the behaviors of a custom machine when inserted in an [upgrade item component](/custom-machinery-1.21/creating-custom-machines/machine-components/item-component/upgrade.md).

Upgrade items can change the following behaviours : 

* Recipe requirements (items, fluids, energy... consumption and production)
* Machine components (capacity, max/min inputs/outputs)
* Cores amount of the machine processor.

{% hint style="success" %}
You can define any item registered in the game as machine upgrade.
{% endhint %}

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]/upgrade/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 *`_`*

{% hint style="info" %}
Upgrades can also be created using [KubeJS](/custom-machinery-1.21/mod-integrations/kubejs/upgrades.md)
{% endhint %}

### Properties

The upgrade json has 2 mandatory properties and 5 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>

#### Optional properties

<details>

<summary>Requirements</summary>

#### Name : `requirements`

#### Description :&#x20;

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

#### Example :

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

This modifier will half the energy input required to process the recipe.

</details>

<details>

<summary>Components</summary>

#### Name : `components`

#### Description :&#x20;

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

#### Example :

```json
"components": [
    {
        "component": "custommachinery:energy",
	"target": "capacity",
	"operation": "addition",
	"modifier": 1000
    }
]
```

This modifier will add 1000FE to the machine's energy capacity.

</details>

<details>

<summary>Core</summary>

#### Name : `core`

#### Description :&#x20;

A single core modifier, used to modify the amount of cores the machine can use to process recipes.&#x20;

A core modifier has the following properties:&#x20;

* `operation` : addition, multiplication or exponential
* `modifier` : The value applied to the operation.
* `max` : The max amount of cores the machine can have after applying the upgrade.
  * Optional (default = 32).
* `min` : The min amount of cores the machine can have after applying the upgrade.
  * Optional (default = 1).
* `tooltip` : The tooltip displayed on the upgrade item.
  * Optional (A default tooltip will be displayed).

#### Example :

```json
"core": [
    {
	"operation": "addition",
	"modifier": 2
    }
]
```

This core modifier will add 2 cores to the machine processor.

</details>

<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.21/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"],
    "requirements": [
        {
	    "requirement": "custommachinery:speed",
	    "mode": "input",
	    "operation": "multiplication",
	    "modifier": 0.5
	}
    ]
}
```

{% endcode %}

The upgrade below will double the machine's energy buffer, and add a second core to the machine.

<pre class="language-json" data-title="upgrade.json"><code class="lang-json"><strong>{
</strong>    "item": "minecraft:diamond",
    "machines": ["custommachinery:power_crusher"],
    "components": [
        {
	    "component": "custommachinery:energy",
	    "target": "capacity",
	    "operation": "multiplication",
	    "modifier": 2
	}
    ],
    "core": {
        "operation": "addition",
        "modifier": 1
    }
}
</code></pre>