# Lootbags

**KyuubiSoft Lootbags adds lootbag items to a Hytale server. Bags drop from creatures and from mining, players open them with a right-click and get a mix of guaranteed and randomly drawn items. A catalog shows every bag, what is inside, the real chance of every item and where the bag drops.**

:::note[Not the Core lootbag templates]
This page is about the standalone mod **KyuubiSoft Lootbags** (`KyuubiSoftLootbag-2.0.4.jar`). KyuubiSoft Core has its own, separate lootbag templates that Achievements, Quests and the Season Pass "lootbag" reward type use. Those are reward definitions without items, drops or windows. See [Achievement Lootbag Templates](https://wiki.kyuubisoft.com/hytale/achievement-system/lootbags).
:::

---

## How lootbags work

- Every lootbag is a normal item. **Right-click** it in your hand to open it: one bag is used up and its items go into your inventory. Items that do not fit are dropped at your feet. Opening needs `ks.lootbag.user.use`, which every player has by default.
- **Crouch + right-click** places the bag as a block instead. Pressing **F** on a placed bag opens the catalog on that bag; the block stays.
- A bag holds **guaranteed items** (always inside) and a **random pool**. When the bag is opened, a set number of items is drawn from the pool by weight, each at most once unless the bag allows duplicates.
- After opening, the **opening window** lists every item you received. Players who prefer it can get a chat summary instead.
- Bags drop from **creatures** and from **mining** according to drop rules with name patterns such as `Trork_*` or `Ore_Gold*`. Blocks that players placed themselves drop no bags.

---

## Styles and tiers

The plugin ships **150 bags**: 30 styles with 5 tiers each (Common, Uncommon, Rare, Epic, Legendary). The catalog sorts the styles into groups:

| Group | Styles | The ID without tier suffix is the |
|-------|--------|-----------------------------------|
| Cloth | Default, Linen, Leather, Canvas | Common bag |
| Nature & metal | Copper, Mossy, Sandstone, Ocean, Bone | Uncommon bag |
| Gems | Sakura, Frost, Crimson, Emerald, Golden | Rare bag |
| Noble | Silk, Royal, Velvet, Enchanted, Crystal | Epic bag |
| Mythic | Shadow, Volcanic, Ancient, Void, Celestial | Legendary bag |
| Seasonal | Easter, Lavender Easter, Mint Easter, Peach Easter, Sky Easter, Sunny Easter | Common bag |

Item IDs follow `<Style>_Lootbag` for the base tier of a style and `<Style>_Lootbag_<Tier>` for the other tiers. Example for Crystal (base tier Epic): `Crystal_Lootbag_Common`, `Crystal_Lootbag_Uncommon`, `Crystal_Lootbag_Rare`, `Crystal_Lootbag`, `Crystal_Lootbag_Legendary`. Bags you add yourself appear in the group **Custom**. See [Custom Lootbags](./custom-lootbags).

### Contents of the shipped bags

The 24 classic styles follow this pattern (all shipped bags draw without duplicates):

| Tier | Guaranteed items | Drawn from the pool | Pool size |
|------|------------------|---------------------|-----------|
| Common | 1 | 1 | 3 |
| Uncommon | 2 | 2 | 4 |
| Rare | 3 | 2 | 5 |
| Epic | 4 | 3 | 6 |
| Legendary | 5 | 4 | 7 |

The six Easter styles have slightly different numbers (for example 2 or 3 guaranteed items on Epic and Legendary). The catalog always shows the exact contents.

:::note[Easter items]
The base items `Easter_Lootbag`, `Easter_Mint_Lootbag`, ... are the common Easter bags and are named "(Common)". The uncommon Easter bags have their own items (`Easter_Lootbag_Uncommon`, `Easter_Mint_Lootbag_Uncommon`, ...). Players may still hold items called `Easter_*_Lootbag_Common` from older versions; they stay in the game and open the common Easter bag of their style.
:::

---

## Windows

All windows use the KyuubiSoft "Goldfiligran" look. Its textures are inside the jar, so there is nothing extra to install.

| Window | Opened by | Content |
|--------|-----------|---------|
| [Catalog](./ui-pages#catalog) | `/kslootbags`, F on a placed bag, `/kslootbags crate <id>`, "View in catalog" in the opening window, a Core NPC with the ID `showcase_lootbag` | Every style with its tiers, filters All / Owned, live search, guaranteed and random items with the chance per bag, "Where to find" |
| [History](./ui-pages#history) | tab in the catalog | Your record (bags opened, items received, per tier, most opened) and your last 50 openings |
| [Latest finds](./ui-pages#latest-finds) | tab in the catalog | The best item of each of the last 30 openings on the server |
| [Opening window](./ui-pages#opening-window) | opening a bag | Every item received, guaranteed and drawn apart, the chance of the drawn ones, items on the ground, "Open another (n)" |
| [Admin panel](./admin-panel) | `/lbadmin panel`, Core admin menu | Bags editor, drop rules, give, statistics, settings |

---

## Commands

| Command | Aliases | Description |
|---------|---------|-------------|
| `/kslootbags` | `/lb`, `/lootbag` | Opens the catalog |
| `/kslootbags crate <id>` | | Opens the catalog on one bag |
| `/kslootbags stats` | | Your lootbag statistics in chat |
| `/kslootbags settings animation on\|off` | | Opening window on, or chat summary only |
| `/kslootbagsadmin panel` | `/lbadmin panel` | Opens the admin panel |
| `/kslootbagsadmin give <id> [amount]` | `/lbadmin give` | Gives you a bag |
| `/kslootbagsadmin edit <id> <property> <value>` | `/lbadmin edit` | Changes a bag and saves it |
| `/kslootbagsadmin reload` | `/lbadmin reload` | Reloads config, bags and drop rules |
| `/kslootbagsadmin list` | `/lbadmin list` | Lists every bag |
| `/kslootbagsadmin preview <id>` | `/lbadmin preview` | Simulates one opening |
| `/kslootbagsadmin lang <code>` | `/lbadmin lang` | Sets your language |

Full syntax on [Commands](./commands), nodes on [Permissions](./permissions).

---

## Where to go

| Page | Read it for |
|------|-------------|
| [Getting Started](./getting-started) | Installing, the files the plugin creates, a first test |
| [Commands](./commands) | Every player and admin command |
| [Configuration](./configuration) | `config.json`, the bag file, the drop rules, languages, player data |
| [Permissions](./permissions) | Permission nodes and what they cover |
| [Admin Panel](./admin-panel) | The admin window section by section |
| [UI Pages](./ui-pages) | Catalog, history, latest finds, opening window, tooltips |
| [Custom Lootbags](./custom-lootbags) | Creating and changing bags, IDs and styles |
| [FAQ & Troubleshooting](./faq) | Common questions and problems |
| [API & Integration](./api-reference) | Using the bags from other plugins and systems |
| [Changelog](./changelog) | What changed in each version |

---

## Quick Reference

| Item | Details |
|------|---------|
| **Product** | KyuubiSoft Dropable Lootbags ([BuiltByBit](https://builtbybit.com/resources/kyuubisoft-dropable-lootbags.99744/)) |
| **Plugin** | KyuubiSoft Lootbag (manifest `kyuubisoft:lootbag`) |
| **Version** | 2.0.4 (2026-11-09) |
| **Jar** | `KyuubiSoftLootbag-2.0.4.jar` |
| **Player command** | `/kslootbags` (aliases `/lb`, `/lootbag`), `/kslang` (language selection shared by all KyuubiSoft mods; the first one that loads registers it) |
| **Admin command** | `/kslootbagsadmin` (alias `/lbadmin`) |
| **Data folder** | `mods/kyuubisoft_lootbag/` |
| **Bags** | `configs/lootbags.json` (shipped), `custom/custom_lootbags.json` (yours) |
| **Drop rules** | `configs/drop_tables.json` |
| **Localization** | `localization/<lang>.json`, 9 languages |
| **Bags shipped** | 150 (30 styles x 5 tiers) |
| **Required** | KyuubiSoft Core |
| **Optional** | DynamicTooltipsLib (lootbag tooltips with tier and contents) |

---

## Requirements

- Hytale server 0.7.x (built against 0.7.0)
- Java 25
- **KyuubiSoft Core.** Core is a required dependency in the manifest: without Core the server does not load Lootbags. Opening a bag, `/lbadmin give`, `/lbadmin panel` and pressing F on a placed bag use Core.
- DynamicTooltipsLib is optional. Without it the bags show Hytale's normal item tooltip.