> For the complete documentation index, see [llms.txt](https://docs.mipcraft.eu/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mipcraft.eu/smartgolems/upgrades.md).

# Upgrades

SmartGolems features a **progressive crafting hierarchy** for upgrades. Each upgrade item is a custom item containing persistent NMS tags (`smart_golem_upgrade`, `upgrade_id`, `upgrade_tier`), star ratings in lore (`★☆☆☆☆`), and sequential crafting dependencies.

<figure><img src="/files/rdoJXspr0hcHALdXHSTw" alt=""><figcaption></figcaption></figure>

## 📈 Upgrade Categories & Level Caps

| Upgrade ID    | Display Name      | Max Level | Effect per Level                     | Base Item                       |
| ------------- | ----------------- | :-------: | ------------------------------------ | ------------------------------- |
| `speed`       | Speed Core        |     5     | +0.05 Movement Speed                 | Sugar / Feather                 |
| `work_speed`  | Work Speed Core   |     5     | -1 Tick Action Delay (Instant @ T4+) | Redstone / Clock                |
| `storage`     | Backpack Expander |     5     | +9 Storage Slots (Up to 54 slots)    | Chest / Shulker Box             |
| `range`       | Range Booster     |     5     | +5 Blocks Radius (8 ➔ 33 blocks)     | Spyglass / Ender Eye            |
| `magnet`      | Item Magnet       |     3     | +2 Blocks Vacuum Radius              | Iron Ingot / Lodestone          |
| `step_height` | Step Assist       |     3     | +0.5 Blocks Step Height (Up to 2.5b) | Copper Ingot / Slime            |
| `health`      | Health Plating    |     5     | +10 HP Max Health                    | Glistering Melon / Golden Apple |
| `armor`       | Armor Plating     |     5     | +4 Armor Points                      | Copper Block / Diamond          |
| `combat_ai`   | Combat Module     |     1     | Unlocks Combat Stances               | Iron Sword / Netherite Sword    |
| `filter`      | Filter Module     |     1     | Unlocks Whitelist / Blacklist UI     | Paper / Comparator              |

## 🔄 Progressive Crafting Dependencies

{% hint style="warning" %}
**Sequential Application**: Players must apply upgrades in order: Tier 1 ➔ Tier 2 ➔ Tier 3 ➔ Tier 4 ➔ Tier 5. You cannot skip tiers!
{% endhint %}

Each tiered recipe in `config.yml` references the previous tier as an exact crafting ingredient:

```yaml
# Example: Speed Core Progression
speed_1: (Sugar + Feather + Redstone) ➔ Speed Core I [★☆☆☆☆]
speed_2: (Speed Core I + Redstone + Gold) ➔ Speed Core II [★★☆☆☆]
speed_3: (Speed Core II + Diamond + Redstone) ➔ Speed Core III [★★★☆☆]
speed_4: (Speed Core III + Emerald + Blaze Powder) ➔ Speed Core IV [★★★★☆]
speed_5: (Speed Core IV + Nether Star + Netherite Ingot) ➔ Speed Core V [★★★★★]
```

## 🧪 Applying Upgrades

{% stepper %}
{% step %}

## Craft the upgrade item

Craft the upgrade item in a crafting table.
{% endstep %}

{% step %}

## Right-click the golem

Right-click the golem while holding the upgrade item in your hand.
{% endstep %}

{% step %}

## Confirm the upgrade

The golem plays an upgrade chime and particle burst, permanently increasing its stats!
{% endstep %}
{% endstepper %}