Custom Lootbags

This guide explains how to create your own lootbag definitions, modify existing ones, and manage them through both the admin panel and JSON files.

---

Overview

The Lootbags system loads definitions from two sources, in order:

1. configs/lootbags.json -- The standard 120 lootbag definitions (versioned, never edited manually)
2. custom/custom_lootbags.json -- Your custom definitions and overrides (never overwritten by updates)

Custom definitions are merged after standard ones. If a custom definition uses the same ID as a standard one, it overrides the standard definition entirely.

---

Method 1: JSON File

Create or edit custom/custom_lootbags.json in the plugin data folder. The file uses a flat format where each key is the lootbag item ID.

Minimal Example

{
  "MyServer_StarterPack": {
    "name": "Starter Pack",
    "rarity": "common",
    "items": [
      { "itemId": "Food_Bread", "amount": 10 },
      { "itemId": "Tool_Hatchet_Crude", "amount": 1 }
    ]
  }
}

Full Example (Hybrid)

{
  "MyServer_VIP_Lootbag": {
    "name": "VIP Lootbag",
    "description": "Exclusive rewards for VIP players",
    "icon": "Chest_Gold",
    "rarity": "legendary",
    "guaranteedItems": [
      { "itemId": "Gem_Diamond", "amount": 5 },
      { "itemId": "Ingot_Gold", "amount": 20 },
      { "itemId": "Potion_Health", "amount": 3 },
      { "itemId": "Food_Feast", "amount": 1 },
      { "itemId": "Enchanted_Book", "amount": 1 }
    ],
    "pickCount": 4,
    "allowDuplicates": false,
    "pool": [
      { "itemId": "Rare_Artifact", "amount": 1, "weight": 5 },
      { "itemId": "Enchanted_Sword", "amount": 1, "weight": 10 },
      { "itemId": "Dragon_Scale", "amount": 2, "weight": 8 },
      { "itemId": "Celestial_Shard", "amount": 1, "weight": 3 },
      { "itemId": "Ancient_Coin", "amount": 10, "weight": 15 },
      { "itemId": "Magic_Dust", "amount": 5, "weight": 20 },
      { "itemId": "Rare_Gem", "amount": 1, "weight": 12 }
    ]
  }
}

Definition Fields

Field	Type	Required	Default	Description
name	String	No	"Lootbag"	Display name shown in UI and tooltips
description	String	No	null	Description text for tooltips
icon	String	No	"Chest_Wood"	Item icon ID used in catalog displays
rarity	String	No	"common"	Rarity tier (see below)
items	LootItem[]	No	null	Fixed items (Type A -- all items always given)
guaranteedItems	LootItem[]	No	null	Guaranteed items (Type C -- always given alongside pool picks)
pool	PoolItem[]	No	null	Weighted random pool (Type B and C)
pickCount	Integer	No	0	Number of items to randomly pick from the pool
allowDuplicates	Boolean	No	false	Whether the same pool item can be picked multiple times

Rarity Tiers

Rarity	Color	Glow Color (placed blocks)
common	Grey (#AAAAAA)	None
uncommon	Green (#55FF55)	Green
rare	Blue (#5555FF)	Blue
epic	Purple (#AA00AA)	Purple
legendary	Gold (#FFAA00)	Gold

---

Three Loot Types

Type A: Fixed Items

All items are always given. No randomness. Use the items field.

{
  "Event_FixedReward": {
    "name": "Event Reward",
    "rarity": "rare",
    "items": [
      { "itemId": "Trophy_Gold", "amount": 1 },
      { "itemId": "Ingot_Gold", "amount": 50 },
      { "itemId": "Gem_Diamond", "amount": 10 }
    ]
  }
}

Type B: Random Pool

Items are randomly selected from a weighted pool. No guaranteed items. Use pool and pickCount.

{
  "MysteryBox_Rare": {
    "name": "Mystery Box",
    "rarity": "rare",
    "pickCount": 3,
    "allowDuplicates": false,
    "pool": [
      { "itemId": "Gem_Diamond", "amount": 1, "weight": 5 },
      { "itemId": "Gem_Emerald", "amount": 2, "weight": 10 },
      { "itemId": "Ingot_Gold", "amount": 5, "weight": 20 },
      { "itemId": "Ingot_Iron", "amount": 10, "weight": 30 },
      { "itemId": "Food_Cheese", "amount": 5, "weight": 35 }
    ]
  }
}

Weight calculation: An item's selection probability equals its weight divided by the total weight of all remaining pool items. In the example above, Iron Ingot has a 30/100 (30%) chance of being picked first. After each pick (with allowDuplicates: false), the picked item is removed from the pool and weights are recalculated.

Type C: Hybrid

Guaranteed items plus random picks from a pool. Use guaranteedItems, pool, and pickCount.

{
  "Dungeon_Boss_Lootbag": {
    "name": "Boss Lootbag",
    "rarity": "epic",
    "guaranteedItems": [
      { "itemId": "Ingot_Gold", "amount": 10 },
      { "itemId": "Potion_Health", "amount": 5 }
    ],
    "pickCount": 3,
    "allowDuplicates": true,
    "pool": [
      { "itemId": "Weapon_Sword_Epic", "amount": 1, "weight": 5 },
      { "itemId": "Armor_Chestplate_Epic", "amount": 1, "weight": 5 },
      { "itemId": "Gem_Diamond", "amount": 3, "weight": 15 },
      { "itemId": "Gem_Ruby", "amount": 2, "weight": 20 },
      { "itemId": "Ancient_Coin", "amount": 5, "weight": 25 },
      { "itemId": "Magic_Dust", "amount": 10, "weight": 30 }
    ]
  }
}

With allowDuplicates: true, the same item can be picked multiple times. This is useful when the pool is small relative to pickCount.

---

Default Loot Scaling

The 120 built-in lootbags follow a scaling pattern based on rarity:

Rarity	Guaranteed Items	Pool Picks	Pool Size
Common	1	1	3
Uncommon	2	2	4
Rare	3	3	5
Epic	4	3	6
Legendary	5	4	7

You are not required to follow this pattern for custom lootbags.

---

Method 2: Admin Panel Editor

Use the in-game admin panel's Catalog tab to edit definitions visually:

1. Open the admin panel: /lbadmin panel
2. Go to the Catalog tab
3. Click any lootbag to open the detail editor
4. Edit name, picks, rarity, duplicates, and items
5. Click Save to persist changes

All changes made through the editor are saved to custom/custom_lootbags.json.

See the Admin Panel page for a detailed guide on the editor interface.

---

Method 3: Edit Command

Use the /lbadmin edit command for quick changes without opening the panel:

# Change rarity
/lbadmin edit MyServer_VIP_Lootbag rarity legendary

# Change display name (supports spaces)
/lbadmin edit MyServer_VIP_Lootbag name VIP Supreme Lootbag

# Set pool pick count
/lbadmin edit MyServer_VIP_Lootbag picks 4

# Toggle duplicate pool picks
/lbadmin edit MyServer_VIP_Lootbag dupes true

# Add a guaranteed item
/lbadmin edit MyServer_VIP_Lootbag gadd Gem_Diamond 5

# Add a pool item (with weight)
/lbadmin edit MyServer_VIP_Lootbag padd Rare_Artifact 1 25

# Remove last guaranteed item
/lbadmin edit MyServer_VIP_Lootbag gdel

# Remove last pool item
/lbadmin edit MyServer_VIP_Lootbag pdel

All changes are auto-saved to custom/custom_lootbags.json.

---

Overriding Standard Definitions

To modify a built-in lootbag, use its exact ID. For example, to change the Default common lootbag:

{
  "Default_Lootbag": {
    "name": "Starter Lootbag",
    "rarity": "common",
    "guaranteedItems": [
      { "itemId": "Food_Bread", "amount": 10 },
      { "itemId": "Tool_Pickaxe_Crude", "amount": 1 }
    ],
    "pickCount": 2,
    "pool": [
      { "itemId": "Potion_Health_Lesser", "amount": 2, "weight": 20 },
      { "itemId": "Tool_Hatchet_Crude", "amount": 1, "weight": 15 },
      { "itemId": "Food_Cheese", "amount": 3, "weight": 25 }
    ]
  }
}

The custom definition completely replaces the standard one with the same ID.

---

Adding Drops for Custom Lootbags

After creating a custom lootbag, add it to the drop tables so it drops from mobs or blocks:

Via JSON

Edit configs/drop_tables.json:

{
  "mobDrops": {
    "Boss_*": [
      { "lootbagId": "Dungeon_Boss_Lootbag", "chance": 0.25 }
    ]
  }
}

Via Admin Panel

1. Open /lbadmin panel and go to the Drops tab
2. Select Mob or Block type
3. Enter the pattern, your custom lootbag ID, and the chance percentage
4. Click Add

---

Localization

Custom lootbag names and descriptions can be localized by adding keys to your language files in localization/:

Key Pattern	Value
lootbag.name.<id>	Localized display name
lootbag.desc.<id>	Localized description

localization/en-US.json

{
  "lootbag.name.MyServer_VIP_Lootbag": "VIP Lootbag",
  "lootbag.desc.MyServer_VIP_Lootbag": "Exclusive rewards for VIP players"
}

If no localization key exists, the name and description fields from the JSON definition are used as fallback.

---

Reload After Changes

After editing JSON files on disk, reload without restarting:

/lbadmin reload

This reloads all lootbag definitions (standard + custom), drop tables, and localization files. Changes made through the admin panel or edit command are auto-saved and do not require a manual reload.