Skip to content

Custom Lootbags

There are three ways to create or change a bag. All three write to custom/custom_lootbags.json; the shipped file configs/lootbags.json is never changed by the plugin.

WayGood for
Admin panel (/lbadmin panel, section Bags)Everything, with item search, live chances and checks before saving. Recommended
JSON fileMany bags at once, your own item look (visualItemId), descriptions
/lbadmin editQuick single changes from the chat or the console

A bag’s tier is its rarity. Its style comes from the ID:

  • <Style>_Lootbag and <Style>_Lootbag_<Tier> (Tier = Common, Uncommon, Rare, Epic or Legendary) belong to the style <Style>. The catalog shows all bags of a style in one row with one button per tier.
  • Every other ID is a style of its own with a single bag.
  • The 30 shipped styles sit in their groups (Cloth, Nature & metal, Gems, Noble, Mythic, Seasonal). Every other style is listed under Custom.

So you can build your own style with several tiers: Event_Lootbag (rarity common), Event_Lootbag_Rare (rarity rare) and Event_Lootbag_Legendary (rarity legendary) show up as one “Event” row with three tiers.

Each style holds one bag per tier. When two bags of a style have the same rarity, the second one gets its own catalog row. The tier word in an ID is only used to find the style: Event_Lootbag_Rare with rarity epic is shown as the epic Event bag.


  1. Open /lbadmin panel and go to Bags.
  2. Type an ID into the field at the bottom of the list (3 to 48 letters, digits or _, for example Event_Lootbag) and click + New.
  3. Set the name, tier, picks and duplicates.
  4. Choose Guaranteed or Pool under Add to, search an item (at least 2 letters) and click a result. Set amounts and weights in the tables; the chance column shows the real chance per bag.
  5. Click Save.

The bag is live at once: its item is created (it looks like the Default bag of its tier), sent to every online player, and the bag appears in the catalog the next time a player opens it. You can now give it in Give and add drop rules for it in Drop rules. Details on every field are on Admin Panel.


Create custom/custom_lootbags.json (or add to it) while the server is stopped, or run /lbadmin reload afterwards. The file is a JSON object with the bag ID as key:

{
"Event_Lootbag_Legendary": {
"name": "Event Lootbag",
"description": "Only during the summer event",
"rarity": "legendary",
"visualItemId": "Golden_Lootbag",
"guaranteedItems": [
{ "itemId": "Ingredient_Bar_Gold", "amount": 10 },
{ "itemId": "Potion_Health_Lesser", "amount": 5 }
],
"pickCount": 2,
"allowDuplicates": false,
"pool": [
{ "itemId": "Ore_Cobalt", "amount": 8, "weight": 50 },
{ "itemId": "Ingredient_Bar_Cobalt", "amount": 3, "weight": 30 },
{ "itemId": "Weapon_Sword_Copper", "amount": 1, "weight": 20 }
]
}
}

This bag always gives both guaranteed stacks and draws 2 different items from the pool of 3; the cobalt ore, with the highest weight, is the most likely. Every field is explained in Configuration.

A bag whose ID is not an existing item needs an item to exist in the game. The plugin creates one at start, on /lbadmin reload and when the bag is saved in the admin panel. It copies the model, icon and look of the item named in visualItemId:

  • First the tier variant is tried: "visualItemId": "Golden_Lootbag" with "rarity": "legendary" uses Golden_Lootbag_Legendary. Without a variant (or for common bags) the item itself is used.
  • Use one of the shipped lootbag items, so the copy keeps the lootbag right-click and place behaviour.
  • The copy’s name in the hotbar is the bag’s name, the same for every language.
  • Bags created in the admin panel get "visualItemId": "Default_Lootbag". Change it in the JSON file and run /lbadmin reload for another look.
  • items: fixed items, same effect as guaranteedItems. The admin panel turns them into guaranteed items when it saves the bag.
  • icon: read but not used in 2.0.4.
  • Your own bags show their name in every window, next to the tier (“Event Lootbag” and “Legendary”); in the chat as “Event Lootbag (Legendary)”.
  • Shipped bags show the translated style name until you give them a name of your own.
  • The keys lootbag.name.<id> and lootbag.desc.<id> of 1.x are no longer used.

Put a bag with the same ID into custom/custom_lootbags.json. It replaces the shipped bag completely, so copy the whole definition from configs/lootbags.json and change what you need. The admin panel does exactly this when you save a shipped bag; its ID line then says “shipped, edited”.

To go back to the shipped version, remove the entry from the custom file and run /lbadmin reload, or click Reset (twice) in the admin panel.


/lbadmin edit Event_Lootbag_Legendary rarity epic
/lbadmin edit Event_Lootbag_Legendary name Summer Lootbag
/lbadmin edit Event_Lootbag_Legendary picks 3
/lbadmin edit Event_Lootbag_Legendary dupes true
/lbadmin edit Event_Lootbag_Legendary gadd Food_Bread 5
/lbadmin edit Event_Lootbag_Legendary padd Weapon_Sword_Copper 1 25
/lbadmin edit Event_Lootbag_Legendary gdel
/lbadmin edit Event_Lootbag_Legendary pdel

Every change is saved to custom/custom_lootbags.json at once. The bag must already exist, and the command does not check item IDs. See Commands.


Add a drop rule in the admin panel (Drop rules, then Add rule), or in configs/drop_tables.json:

{
"mobDrops": {
"Trork_*": [
{ "lootbagId": "Event_Lootbag_Legendary", "chance": 0.01, "minAmount": 1, "maxAmount": 1 }
]
}
}

Add the entry to the existing file instead of replacing it. Run /lbadmin reload after editing the file. See Configuration.


A custom bag is an item like the shipped ones: give it with /lbadmin give <id>, the admin panel, /give, shop or quest item rewards. See API & Integration.