How to Make an Upgrade

An upgrade is something players buy for a placed minion, one tier at a time. Each upgrade is a set of effects, a ladder of tiers with their own costs, and the display shown in the upgrade menu. This page covers making one from scratch.

Quick start

1. Open the /plugins/EcoMinions/upgrades/ folder and copy _example.yml to a new file, e.g. speed.yml. The file name is the upgrade ID.

2. Set name and display.icon.

3. Add the effects the upgrade gives, using %tier_value% for the number that changes per tier.

4. Add each tier under tiers, with its value, stat-delta and cost-options.

5. Add the upgrade ID to a minion's allowed-upgrades, run /minions reload, open that minion's upgrades menu, and confirm it appears.

Naming and IDs

The file name without .yml is the upgrade ID. This is what a minion's allowed-upgrades list and the minion_has_upgrade condition reference. display.icon uses the Item Lookup System, and cost-options use the Price Lookup System.

The structure of an upgrade

# === Display: how it shows in the upgrade menu ===
name: "&bSpeed" # The upgrade's name in the menu.
display:
  icon: sugar # The upgrade's icon in the menu.

# === Effects: what the upgrade does ===
effects: # Effects shared by every tier. %tier_value% is the owned tier's value.
  - id: minion_speed
    args:
      ticks_faster: "%tier_value%"
conditions: [] # Optional. Conditions that must pass for the effects to be active.

# === Tiers: the ladder players buy up ===
tiers:
  1:
    value: 5 # The number %tier_value% resolves to at this tier.
    stat-delta: "-5 ticks" # Menu text describing this tier.
    cost-options: # The ways a player can pay for this tier. They pick one.
      - value: 5000
        type: coins
        display: "&a$%value_commas%"
      - value: 64
        type: stone
        display: "&7%value_commas%x Stone"
    buy-conditions: [] # Optional. Conditions that must pass to buy this tier.
  2:
    value: 10
    stat-delta: "-10 ticks"
    cost-options:
      - value: 12000
        type: coins
        display: "&a$%value_commas%"

Display

How the upgrade shows in the minion's upgrade menu.

name: "&bSpeed" # The upgrade's name in the menu.
display:
  icon: sugar # The upgrade's icon in the menu.

Effects

The effects the upgrade gives. They are written once and shared by every tier, and only the owned tier is ever active. Buying the next tier swaps the old tier out for the new one.

effects: # Effects shared by every tier. %tier_value% is the owned tier's value.
  - id: minion_speed
    args:
      ticks_faster: "%tier_value%"
conditions: [] # Optional. Conditions that must pass for the effects to be active.

Two placeholders work inside the effects:

Permanent effects such as minion_speed need no triggers: they are active while the tier is owned. Triggered effects, which is almost every stock libreforge effect, need a triggers list:

effects:
  - id: multiply_drops
    triggers:
      - minion_mine_block # Runs each time the minion breaks a block.
    args:
      multiplier: "1 + %tier_value%"

For something that should run on a timer, use minion_static_<ticks> rather than minion_tick with every, as it only runs on the ticks it is due. The shipped auto sell upgrade sells every 200 ticks:

effects:
  - id: minion_sell_storage
    triggers:
      - minion_static_200 # Runs every 200 ticks.

Tiers

The ladder players buy up, in order. Tier keys must be whole numbers.

tiers:
  1:
    value: 5 # The number %tier_value% resolves to at this tier.
    stat-delta: "-5 ticks" # Menu text describing this tier.
    cost-options: # The ways a player can pay for this tier. They pick one.
      - value: 5000
        type: coins
        display: "&a$%value_commas%"
      - value: 64
        type: stone
        display: "&7%value_commas%x Stone"
    buy-conditions: [] # Optional. Conditions that must pass to buy this tier.

value has no meaning of its own. It is what %tier_value% resolves to, so it is a tick count, a multiplier or a flag depending on how the effects use it.

Each entry in cost-options is a price, so type can be coins, an item, or any other price type. When there is more than one, the player picks which to pay with. display is required on every entry, and %value% and %value_commas% work inside it.

buy-conditions are checked before the price. Use them to lock a tier behind a minion level, another upgrade, or anything else a condition can check.

Internal placeholders

These work in the upgrade menus in lang.yml.

Where to go next

• Minions: expose the upgrade with allowed-upgrades in Configuring a Minion.

• Compacting: compactor recipes make their own upgrades, see How to Make a Compactor Recipe.

• Levelling: lock tiers behind minion levels with How to Level a Minion.

• Defaults: the shipped upgrades live here.