# Lootbags

# Lootbag Rewards

Documentation for `lootbags.json` — lootbag templates used as achievement rewards.

:::info Not the standalone Lootbag Mod
These are reward definitions, not droppable items. For the **standalone Lootbags mod** with 150 collectible bags (30 styles in 5 tiers), mob/block drops and a catalog window, see [Lootbags Mod](https://wiki.kyuubisoft.com/hytale/lootbags/).
:::

## Overview

Lootbags are reward containers that players open to receive items. A lootbag reward waits in the **Rewards** tab of the [achievement book](./rewards-ui) (`/ksrewards`) until the player opens it. It is rolled once and the result is saved, so a relog never re-rolls it.

### One registry with KyuubiSoft Core

Since 3.0.0 there is one lootbag registry: KyuubiSoft Core's. The bags of this mod's `lootbags.json` (and `custom/custom_lootbags.json`) are registered there, so Core, Quests and other mods can use them by id. If Core already has its own standard or custom bag with the same id, Core's bag wins.

- With **KyuubiSoft Core 2.9.2** or newer, a reload (`/ksadmin reload` or a save in the admin window) applies new, changed and removed bags at once.
- With an older Core, only new bags apply at once; changed and removed bags apply after a restart (the reload message says so).

**Features:**
- **Three lootbag types** - Fixed items, random pool, or hybrid
- **Weighted randomization** - Control item drop chances
- **Rarity system** - Visual distinction by rarity tier
- **Auto-export** - Default templates are created automatically

## Files

| File | Notes |
|------|-------|
| `mods/kyuubisoft_achievements/configs/lootbags.json` | Shipped bags (version 4, 20 bags). Replaced when a new version ships a newer file; an older file is backed up |
| `mods/kyuubisoft_achievements/custom/custom_lootbags.json` | Your own bags and overrides (same id = override). Never overwritten |

---

## Lootbag Types

### Type A: Fixed Items (Guaranteed)

The player receives **all** defined items.

```json
{
  "welcome_gift": {
    "name": "Welcome Gift",
    "description": "A small starter pack for new players",
    "icon": "Furniture_Ancient_Chest_Small",
    "rarity": "common",
    "items": [
      { "itemId": "Food_Bread", "amount": 10 },
      { "itemId": "Furniture_Ancient_Torch", "amount": 16 },
      { "itemId": "Tool_Pickaxe_Wood", "amount": 1 }
    ]
  }
}
```

### Type B: Random Pool

The player receives **X random items** from a weighted pool.

```json
{
  "food_crate": {
    "name": "Food Crate",
    "description": "Provisions for your journey",
    "icon": "Food_Bread",
    "rarity": "common",
    "pickCount": 3,
    "allowDuplicates": true,
    "pool": [
      { "itemId": "Food_Bread", "amount": 5, "weight": 50 },
      { "itemId": "Plant_Fruit_Apple", "amount": 8, "weight": 40 },
      { "itemId": "Food_Fish_Grilled", "amount": 3, "weight": 30 },
      { "itemId": "Potion_Health", "amount": 2, "weight": 10 }
    ]
  }
}
```

### Type C: Hybrid (Guaranteed + Random)

The player receives **guaranteed items** plus **X random items** from the pool.

```json
{
  "playtime_gold": {
    "name": "Gold Loyalty Reward",
    "description": "For dedicated players",
    "icon": "Ore_Gold",
    "rarity": "rare",
    "guaranteedItems": [
      { "itemId": "Ore_Gold", "amount": 25 }
    ],
    "pickCount": 2,
    "allowDuplicates": false,
    "pool": [
      { "itemId": "Rock_Gem_Ruby", "amount": 1, "weight": 20 },
      { "itemId": "Rock_Gem_Emerald", "amount": 1, "weight": 20 },
      { "itemId": "Rock_Gem_Sapphire", "amount": 1, "weight": 20 },
      { "itemId": "Ore_Mithril", "amount": 5, "weight": 15 }
    ]
  }
}
```

---

## Field Reference

### Lootbag Definition

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Display name of the lootbag |
| `description` | string | Yes | Description text |
| `icon` | string | Yes | Item ID for the icon |
| `rarity` | string | No | Rarity tier (see below) |
| `items` | array | No* | Fixed items (Type A) |
| `guaranteedItems` | array | No* | Guaranteed items (Type C) |
| `pickCount` | number | No* | Number of random picks |
| `allowDuplicates` | boolean | No | Allow duplicate picks (default: false) |
| `pool` | array | No* | Pool for random picks |

:::note
*At least `items` OR (`pickCount` + `pool`) must be defined.
:::

### Item Definition

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `itemId` | string | Yes | Item ID (e.g., `Ore_Gold`) |
| `amount` | number | No | Quantity (default: 1) |
| `weight` | number | No* | Weight for random selection |

:::note
*`weight` is required in `pool` arrays, not used in `items`/`guaranteedItems`.
:::

### Rarity Values

| Rarity | Color | Typical Use |
|--------|-------|-------------|
| `common` | Gray (#AAAAAA) | Starter rewards, simple achievements |
| `uncommon` | Green (#55FF55) | Normal achievements |
| `rare` | Blue (#5555FF) | Difficult achievements |
| `epic` | Purple (#AA00AA) | Epic achievements |
| `legendary` | Orange (#FFAA00) | End-game achievements |

---

## Default Templates

The plugin includes these pre-configured lootbags:

### Basic Templates

| ID | Name | Type | Rarity |
|----|------|------|--------|
| `starter_pack` | Starter Pack | Fixed | common |
| `miner_reward` | Miner's Treasure | Fixed | uncommon |
| `combat_loot` | Warrior's Cache | Hybrid | rare |
| `explorer_chest` | Explorer's Chest | Random | epic |
| `legendary_hoard` | Dragon's Hoard | Hybrid | legendary |
| `welcome_gift` | Welcome Gift | Fixed | common |

### Tool & Resource Bundles

| ID | Name | Type | Rarity |
|----|------|------|--------|
| `copper_bundle` | Copper Ore Bundle | Fixed | uncommon |
| `copper_tools` | Copper Tool Set (new in file version 4) | Fixed | uncommon |
| `iron_tools` | Iron Tool Set | Fixed | rare |
| `ore_bundle_common` | Ore Bundle (Basic) | Fixed | common |
| `ore_bundle_rare` | Ore Bundle (Rare) | Fixed | rare |
| `ore_bundle_epic` | Ore Bundle (Epic) | Fixed | epic |
| `lumberjack_pack` | Lumberjack Pack | Fixed | uncommon |

### Activity Rewards

| ID | Name | Type | Rarity |
|----|------|------|--------|
| `food_crate` | Food Crate | Random | common |
| `builder_bundle` | Builder Bundle | Random | uncommon |
| `hunter_reward` | Hunter's Bounty | Random | uncommon |
| `social_gift` | Social Gift | Fixed | common |

### Playtime Rewards

| ID | Name | Type | Rarity |
|----|------|------|--------|
| `playtime_bronze` | Bronze Loyalty Reward | Fixed | common |
| `playtime_silver` | Silver Loyalty Reward | Fixed | uncommon |
| `playtime_gold` | Gold Loyalty Reward | Hybrid | rare |

---

## Example: Achievement with Lootbag

```json
{
  "id": "welcome",
  "category": "social",
  "iconItem": "Furniture_Ancient_Chest_Small",
  "difficulty": "easy",
  "trigger": {
    "type": "playtime_minutes",
    "count": 1
  },
  "rewards": [
    { "type": "lootbag", "lootbagId": "welcome_gift" }
  ]
}
```

**Localization:**
```properties
achievements.name.welcome=Welcome!
achievements.desc.welcome=Play for 1 minute
```

---

## Weight Calculation

For random pools, the probability of selecting an item is:

```
Probability = item_weight / total_weight
```

**Example:**
```json
"pool": [
  { "itemId": "Food_Bread", "amount": 5, "weight": 50 },    // 50/130 = 38.5%
  { "itemId": "Plant_Fruit_Apple", "amount": 8, "weight": 40 },    // 40/130 = 30.8%
  { "itemId": "Food_Fish_Grilled", "amount": 3, "weight": 30 },     // 30/130 = 23.1%
  { "itemId": "Potion_Health", "amount": 2, "weight": 10 }  // 10/130 = 7.7%
]
// Total weight: 130
```

---

## Creating Custom Lootbags

1. Open `custom/custom_lootbags.json` (copy `custom_lootbags.json.example` if it does not exist yet)
2. Add your lootbag definition:

```json
{
  "existing_lootbags": { ... },

  "my_custom_lootbag": {
    "name": "My Custom Reward",
    "description": "A special reward",
    "icon": "Furniture_Ancient_Chest_Small",
    "rarity": "epic",
    "guaranteedItems": [
      { "itemId": "Ore_Gold", "amount": 50 }
    ],
    "pickCount": 3,
    "allowDuplicates": false,
    "pool": [
      { "itemId": "Rock_Gem_Diamond", "amount": 1, "weight": 10 },
      { "itemId": "Rock_Gem_Ruby", "amount": 2, "weight": 30 },
      { "itemId": "Rock_Gem_Emerald", "amount": 2, "weight": 30 },
      { "itemId": "Ingredient_Bar_Gold", "amount": 10, "weight": 30 }
    ]
  }
}
```

3. Reference it in an achievement:

```json
{
  "rewards": [
    { "type": "lootbag", "lootbagId": "my_custom_lootbag" }
  ]
}
```

4. Reload with `/ksadmin reload` (see [One registry with KyuubiSoft Core](#one-registry-with-kyuubisoft-core) for when changes apply)

---

## Best Practices

1. **Balance weights carefully** - Very low weights may frustrate players
2. **Use appropriate rarities** - Match rarity to achievement difficulty
3. **Consider duplicates** - Set `allowDuplicates: false` for variety
4. **Test lootbags** - Grant the achievement to yourself with `/acadmin grant` and open the bag in the Rewards tab
5. **Descriptive names** - Help players understand what they're getting