Libreforge Components
Libreforge Components
EcoMinions upgrades and minion effects: blocks are built on libreforge - thesame effect/trigger/condition/mutator system used across eco plugins. This page lists every minion-specificcomponent EcoMinions registers, plus the stock libreforge components that are known to work well on minions.
See How to Make an Upgrade and How to Make a Minion for howeffects: blocks are authored in practice.
Triggers
Triggers decide when a triggered effect runs. Pass one or more in an effect's triggers: list.
| Trigger | Fires when | Parameters |
|---|---|---|
minion_mine_block | A minion breaks a target block, before its drops are stored. | player (the owning player, if online), block (the block the minion broke), event (an editable drop event over the block's drops), location, item, value (how many blocks this action broke - more than one for stacked plants) |
minion_storage_full | A minion tries to mine but its storage is full. | player, location |
minion_regen_block | A block a minion mined regenerates. | player, block (the block that regenerated), location |
minion_tick | Every tick an active minion runs. Fires very frequently - for interval behaviour, prefer minion_static_<n> below over every: here. | player, location |
minion_static_<n> | Every n ticks, only for minions that are due - unlike minion_tick + every:, non-due ticks skip dispatch entirely rather than dispatching and discarding. n can be a plain integer (minion_static_200) or an expression, re-evaluated each check. | location |
minion_place | A minion is placed in the world. | player, location |
minion_pickup | A minion is picked up out of the world. | player, location |
minion_upgrade | A player buys an upgrade tier for a minion. | player, location, text (the id of the upgrade that was bought), value (the tier that was bought) |
minion_fuel_start | A minion starts burning a fuel. | player, location, text (the id of the fuel that started burning) |
minion_fuel_expire | The tick a minion's fuel runs out. Only fires for an active minion - an idle minion's fuel is frozen, so it cannot expire while idle. | player, location |
minion_sell | A minion's storage is sold. | player, location, event (an editable drop event over the stacks being sold), value (the money the sale earned) |
minion_level_up | A minion gains a level. Dispatched by EcoMinions itself, not a Bukkit listener - can fire while the owner is offline. | player (the owning player, if online), location, value (the level reached) |
minion_collect | An item is actually stored in a minion's storage (not dispatched for anything that bounced because storage was full). | player (the owning player, if online), item (the item stored), location, value (how many of the item were stored) |
Effects
Bespoke minion effects, with the argument(s) each takes inside args:.
| Effect | Args | What it does |
|---|---|---|
minion_speed | ticks_faster (expression) | Reduces the ticks between a minion's mine cycles. Permanent - no triggers: needed. |
minion_efficiency | ticks_faster (expression) | Reduces the ticks a minion spends breaking a block. Permanent - no triggers: needed. |
minion_radius | blocks (expression) | Widens the area a minion scans for target blocks. Permanent - no triggers: needed. |
minion_height | blocks (expression) | Raises how far up a minion scans for target blocks, from the floor of its box upward. Permanent - no triggers: needed. |
minion_capacity | slots (expression) | Adds stack slots to a minion's storage, up to the type's max-storage-slots. Permanent - no triggers: needed. Resizes live storage; any overflow is dropped in the world rather than lost. |
minion_sell_storage | none | Sells the entire contents of a minion's storage. Triggered - needs a triggers: list (e.g. minion_static_200 for an auto-sell upgrade). |
minion_compact | none | Compacts a minion's storage using every compactor recipe the minion owns and currently meets the conditions: for. Does nothing if the minion owns no recipes. Triggered - needs a triggers: list. |
give_minion_xp | amount (expression) | Grants XP to a minion, letting a fuel or an upgrade tier feed levelling progression directly. Triggered - needs a triggers: list. |
minion_speed, minion_efficiency, minion_radius, minion_height, and minion_capacity are permanent stat effects: theycontribute to a stat while their holder (the type or upgrade tier) is active, and remove that contribution theinstant it's disabled. Their args value supports full expressions, so %tier_value% and arithmetic on it bothwork.
Conditions
| Condition | Args | Passes when |
|---|---|---|
minion_level_above | level (expression) | The minion's level is at or above the given level. |
minion_level_below | level (expression) | The minion's level is at or below the given level. |
minion_is_type | types (string list) | The minion is one of the given types: miner, woodcutter, farmer. Changed meaning: this used to match minion ids, so minion_is_type: [oak] matched a minion named oak and now matches nothing. |
minion_has_upgrade | upgrade (string, required), tier (expression, optional - defaults to 1) | The minion owns the given upgrade at or above the specified tier. Also works for a compactor recipe's compactor_<recipe id> upgrade id. |
minion_storage_above_percent | percent (expression, 0-100) | The minion's storage is at least the given percentage full. |
minion_has_fuel | none | The minion is currently burning fuel. |
minion_owner_online | none | The minion's owner is online. |
Mutators
Mutators rewrite the trigger data flowing through an effect chain.
| Mutator | What it does |
|---|---|
minion_owner_as_dispatcher | Makes the minion's owner the dispatcher for the rest of the chain, adding a player parameter. Lets an admin say "run the rest of this on the player" explicitly, rather than relying on the trigger data already carrying a player. |
minion_location_to_target_block | Sets the chain's location to the block the minion is acting on. |
Stock components that work on minions
Minion drops are routed through a real libreforge drop event - that's what the event parameter onminion_mine_block and minion_sell is. Because of that, stock libreforge components that operate on dropevents work on minions exactly as they would on a player's own mining, including:
multiply_drops- multiplies the quantity of items dropped (used for fortune-style upgrades).autosmelt- smelts drops into their furnace output before they're stored.drop_xp- grants XP for the drop.cancel_drops- cancels the drop entirely.telekinesis- sends drops straight to storage/inventory instead of the ground.The
blocks/items/entitiesfilter arguments many stock effects accept, to restrict which blocks,items, or entities an effect applies to.
Any of these can be dropped straight into an upgrade's or a minion's effects: list alongside theminion-specific effects above, with a triggers: list of [minion_mine_block] (or [minion_sell] forsell-time effects).
The owner caveat
Most minion triggers carry a player parameter, but it's only populated while the minion's owner is online -an idle minion still fires triggers like minion_tick, but with a null player. Any stock effect that targetsthe trigger's player - send_message, give_money, and similar - silently does nothing while the owner isoffline, because there is no player for it to act on.
If an effect needs to reach the owner regardless, gate it with the minion_owner_online condition so it'sclear the effect is owner-dependent, or use the minion_owner_as_dispatcher mutator to retarget the chain atthe owner explicitly.
This caveat applies just as much to a minion's level-up-effects (seeHow to Level a Minion) - a minion can level up while its owner is offline, so anowner-targeting effect there needs the same minion_owner_online guard.