Custom Loot Table

The shared loot format defines custom items, vanilla items, currency and commands for bosses, treasure chests, quests and arenas. Each entry has its own chance roll; the table does not choose just one winning entry.

For automatic equipment coverage across classes and difficulties, see automatic class loot. Its separate baseline roll can run alongside uniqueLootList. Keep authored relics, scripted equipment and other special rewards in this loot table. Entries pointing to itemType: CLASS_LOOT items are candidates for the class-loot selection and are skipped by ordinary boss death rolls. Other authored entries retain their independent rolls.

Please note that this is the latest format and the one that is recommended to use, but some alternative older formats exist.

Note: Legacy format support is still available using the colon-separated syntax: filename.yml:chance:permission. However, the modern format shown below is recommended for new configurations.

In that legacy syntax the chance and permission are optional, so a bare filename.yml drops the item at 100%. A legacy entry with more than three colon-separated parts is rejected.

Every entry is checked when its file loads. An unknown or repeated key, a key without a value, a chance that is not a finite number, an amount, currencyAmount, wave or itemLevel that is not a whole number, or an invalid material rejects that entry with a Failed to parse entry ... due to invalid: <reason> warning, and the rest of the table still loads. Keys are case-insensitive.

Use the owning feature's key: uniqueLootList for bosses, lootList for treasure chests, customRewards for quests, or rawArenaReward for arenas. Quest customRewards accepts string entries; use the colon-separated filename=...:chance=... form there instead of YAML maps.

Delivery by loot source

All four entry types work for Custom Boss loot (uniqueLootList). For ordinary authored entries, delivery follows putLootDirectlyIntoPlayerInventory:

Entry type	putLootDirectlyIntoPlayerInventory: false (default)	putLootDirectlyIntoPlayerInventory: true
Elite item (filename)	Personal ground drop or shared equipment vote	Personal inventory delivery or shared equipment vote
Vanilla item (material)	Ground drop	Inventory delivery; overflow drops at the player
Elite coins (currencyAmount)	Collectible coin shower	Currency credited directly
Command (command=)	Runs from the console	Runs from the console

Boss rewards roll separately for each recorded damage contributor, excluding players locked out from that instanced boss. This authored-loot path has no separate 10% damage threshold. Nearby party members receiving shared credit without damaging the boss receive only non-equipment elite-item entries through this path, not vanilla, currency or command entries. Anti-exploit activation suppresses this death loot.

Bosses spawned inside another plugin's instance through the EliteMobs instanced-boss API ignore putLootDirectlyIntoPlayerInventory and never start a party or group vote. Their loot always drops on the ground at the boss as in the false column, with elite items as personal drops, so it stays in that instance's world.

Treasure chests use the same ground/inventory setting; quests and arenas deliver directly. All four support the entry types below; quests accept only string entries. Boss command loot runs per successful contributor roll. For the separate boss-death command syntax, see onDeathCommands.

Dropping elite items:

Key	Details	Values	Default
filename	Sets the file name of the Custom Item to use.	Filename	none

Example

uniqueLootList:
  - filename: magmaguys_toothpick.yml

This will make the mob drop 1 of MagmaGuy's Toothpick with a 100% drop chance.

General settings:

Key	Details	Values	Default
chance	One independent entry roll, where 1.0 is 100%. Use values from 0.0 to 1.0.	Double	1.0
amount	Number of item copies or command executions after a successful roll. It does not multiply currency; use currencyAmount for the payout.	Integer	1
permission	Sets the permission node required for players to receive this loot. Supported by elite item, currency and command entries. Vanilla item entries never read it, in either format.	String	none

An entry with amount <= 0 or chance <= 0 does not roll; a non-numeric or non-finite chance rejects the entry when the file loads. A chance above 1.0 always passes; it is not a percentage such as 50. Once a roll passes, delivery does not reroll for each copy. Quest previews perform their own chance rolls and are not a reservation of the eventual rewards.

Example

uniqueLootList:
  - filename: magmaguys_toothpick.yml
    chance: 0.5
    amount: 10
    permission: elitemobs.loot.rare

This will make the mob drop 10 of MagmaGuy's Toothpick with a 50% drop chance, but only for players with the elitemobs.loot.rare permission.

Dropping elite coins:

Key	Details	Values	Default
currencyAmount	Sets the amount of coins that will be dropped.	Integer	none

currencyAmount must be a whole number, and it must be positive to deliver currency. A positive amount does not multiply it, but amount <= 0 disables the entry. A zero or negative currencyAmount loads in either format but delivers nothing.

Direct currency rewards pass through the economy handler and repay gambling debt first. Ground delivery uses a collectible coin shower and can receive the Harvester skill bonus; the direct currency-entry path does not apply that bonus. Coins in a shower are credited when collected, not when the entry rolls.

Example

uniqueLootList:
  - currencyAmount: 344
    chance: 0.5

This gives each eligible boss contributor a 50% chance at a base reward of 344 Elite Coins. Use lootList for the same entry in a treasure chest.

Dropping vanilla items:

Key	Details	Values	Default
material	Sets the item material. Material names are case-insensitive in both formats. type is accepted as an alias; setting both material and type rejects the entry.	Material	none

Example

uniqueLootList:
  - material: APPLE
    chance: 0.3
    amount: 5

This will make the mob drop 5 Apples with a 30% drop chance.

Both ground and direct-inventory delivery use one entry roll. In this example a successful roll delivers all 5 Apples. Direct delivery supports bosses, chests, quests and arenas, and drops inventory overflow at the player's location. AIR materials and non-positive amounts deliver nothing. Vanilla entries do not enforce permission.

Executing commands on loot drop:

You can execute console commands when loot drops. This is useful for integrating with other plugins or providing custom rewards. Command entries accept the colon-separated string format and, except in quest customRewards, YAML maps.

Key	Details	Values	Default
command	Sets the console command to execute. Use %player% as a placeholder for the player's name.	String	none

In the string format the command must not contain a :, because the entry is split on that character. An = inside the command is fine. Use a YAML map when the command needs a colon.

Command chance and repetition

Command entries roll chance once, just like other entries. After a successful roll, the command is dispatched amount times. There is no second or inverted roll:

• chance=1.0 (the default) always passes.
• chance=0.5 passes 50% of the time.
• amount=3 executes three times if that one roll passes.

The player must satisfy permission, and the command must be nonblank. The command's own requirements still apply. Since it runs as the console, use %player% to identify the reward recipient.

Example

customRewards:
  - command=give %player% diamond 1:chance=0.5:amount=1:permission=elitemobs.loot.command

This quest reward executes give <player> diamond 1 from the console on turn-in 50% of the time. %player% becomes the player's name, and the player needs elitemobs.loot.command. The same string also works under a boss's uniqueLootList, with a separate roll for each eligible contributor.

Arena rewards:

When making arena loot tables, please make sure that you start your loot table with rawArenaReward: instead of uniqueLootList:.

Key	Details	Values	Default
wave	Completed arena wave that awards this entry. Every entry type accepts it in either format.	Integer	-1
itemLevel	Sets the level of the loot drop. Only used by arenas, and only meaningful for elite item (filename) entries. Accepted in either format.	Integer	1

Both of these have traps

• Only entries with a wave of 1 or higher are ever registered as wave rewards. An arena reward entry with no wave is parsed and accepted, but no wave will ever hand it out.
• itemLevel defaults to 1, not to the arena or player level. A scalable elite item awarded by an arena without an explicit itemLevel therefore drops as a level 1 item.

Example

rawArenaReward:
  - material: BREAD
    wave: 1
    amount: 10
    chance: 0.5
  - filename=magmaguys_toothpick.yml:wave=1:itemLevel=2

After wave 1, the Bread entry has one 50% roll. If it passes, the player receives 10 Bread, with overflow dropped on the ground. The custom-item entry has a 100% entry chance and requests one MagmaGuy's Toothpick at item level 2; its item definition's scalability still controls the generated level. The arena's player eligibility and level-difference checks apply before these rewards.

The two entries use different formats only to show both; wave and itemLevel work in either format.

Instanced Dungeons:

Key	Details	Values	Default
difficultyID	Filters an elite-item entry by the recipient's current dungeon difficulty; YAML maps also accept a list of IDs.	String, number, or list	none

difficultyID is read for elite item (filename) entries in both YAML maps and the colon-separated string format. Maps also support lists, such as difficultyID: [normal, hard]. Vanilla, currency and command entries reject it as an unknown key. IDs and names follow the dungeon's difficulty resolver: 0/1/2, Normal/Hard/Mythic, or the package's Easy/Medium/Hard convention. Unknown IDs retain exact matching. An empty list or a blank ID rejects the entry when the file loads.

The filter is checked for elite-item rewards from bosses, treasure chests, quests and arenas. It only restricts a player currently in a dungeon instance; outside one, it is ignored. A boss spawned in another plugin's instance through the instanced-boss API is filtered by the difficulty that plugin assigned to it. A normal arena instance is not a dungeon instance. Chest, quest and arena rewards remain personal rather than entering a shared equipment vote.

For boss delivery, the entry behaves as follows:

• Dungeon difficulty matches the difficultyID: equipment enters the boss's shared group loot table. Non-equipment rewards keep personal delivery. The boss's eligible combat contributors can claim shared equipment; players already locked out from that boss are removed before the vote.
• Dungeon difficulty does not match: the entry is skipped.
• The player is not in an instanced dungeon at all: the difficultyID is ignored. Equipment uses party Need / Greed when at least two eligible party members are nearby, or follows normal personal delivery otherwise. Non-equipment rewards stay personal.

Without a difficultyID filter, equipment can still enter party loot, but that field's dungeon-specific shared-table branch does not run. Class-loot candidates use their separate class-selection and difficulty rules described above.

Example

uniqueLootList:
  - filename: magmaguys_toothpick.yml
    chance: 0.5
    difficultyID: 1

This will make the mob drop 1 MagmaGuy's Toothpick with a 50% drop chance if the players defeated the boss on difficulty 1.