Lootbags Configuration

Documentation for lootbags.json - configurable lootbag templates that can be used as achievement rewards.

Overview

Lootbags are reward containers that players can open to receive items. Unlike direct item rewards, lootbags are stored as pending rewards and collected via the /rewards command.

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

Auto-Export

The lootbags.json file is automatically exported to your server config folder on first start:

Path: Server/Config/lootbags.json

After export, you can freely customize the file. The plugin will not overwrite your changes.

---

Lootbag Types

Type A: Fixed Items (Guaranteed)

The player receives all defined items.

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

Type B: Random Pool

The player receives X random items from a weighted pool.

{
  "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": "Food_Apple", "amount": 8, "weight": 40 },
      { "itemId": "Food_Meat_Cooked", "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.

{
  "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": "Gem_Ruby", "amount": 1, "weight": 20 },
      { "itemId": "Gem_Emerald", "amount": 1, "weight": 20 },
      { "itemId": "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

Tool & Resource Bundles

ID	Name	Type	Rarity
copper_tools	Copper Toolset	Fixed	uncommon
iron_tools	Iron Toolset	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

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

Localization:

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:

"pool": [
  { "itemId": "Food_Bread", "amount": 5, "weight": 50 },    // 50/130 = 38.5%
  { "itemId": "Food_Apple", "amount": 8, "weight": 40 },    // 40/130 = 30.8%
  { "itemId": "Food_Meat", "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 Server/Config/lootbags.json
2. Add your lootbag definition:

{
  "existing_lootbags": { ... },

  "my_custom_lootbag": {
    "name": "My Custom Reward",
    "description": "A special reward",
    "icon": "Chest_Gold",
    "rarity": "epic",
    "guaranteedItems": [
      { "itemId": "Ore_Gold", "amount": 50 }
    ],
    "pickCount": 3,
    "allowDuplicates": false,
    "pool": [
      { "itemId": "Gem_Diamond", "amount": 1, "weight": 10 },
      { "itemId": "Gem_Ruby", "amount": 2, "weight": 30 },
      { "itemId": "Gem_Emerald", "amount": 2, "weight": 30 },
      { "itemId": "Material_Gold", "amount": 10, "weight": 30 }
    ]
  }
}

3. Reference it in an achievement:

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

4. Reload the plugin or restart the server

---

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 - Use admin commands to verify contents
5. Descriptive names - Help players understand what they're getting