# 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.

| Way | Good for |
|-----|----------|
| [Admin panel](#in-the-admin-panel) (`/lbadmin panel`, section Bags) | Everything, with item search, live chances and checks before saving. Recommended |
| [JSON file](#in-the-json-file) | Many bags at once, your own item look (`visualItemId`), descriptions |
| [`/lbadmin edit`](#with-lbadmin-edit) | Quick single changes from the chat or the console |

---

## IDs, styles and tiers

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.

---

## In the admin panel

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](./admin-panel#bags).

---

## In the JSON file

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:

```json
{
  "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](./configuration#bag-fields).

### The item of a new bag

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.

:::caution
Without `visualItemId` the plugin cannot create the item and logs `Auto-derived visual item not found: ... for <id>`. The bag is then listed in the catalog, but it cannot be given, dropped or opened.
:::

### Fields you do not need

- `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.

### Names

- 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.

---

## Changing a shipped bag

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.

---

## With `/lbadmin edit`

```
/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](./commands#lbadmin-edit-id-property-value).

---

## Making the bag drop

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

```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](./configuration#drop-rules-drop_tablesjson).

---

## Handing it out elsewhere

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](./api-reference).