Lootbags

Lootbag Reward Templates (Core)

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

:::info Not the standalone Lootbag Mod This page documents the Core lootbag template system — simple reward containers used by Achievements and Quests. These are reward definitions, not droppable items.

For the standalone Lootbags mod with 120 collectible items, mob/block drops, themed families, and a reveal animation, see Lootbags Mod. :::

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

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

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

Open Server/Config/lootbags.json
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 }
    ]
  }
}

Reference it in an achievement:

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

Reload the plugin or restart the server

Best Practices

Balance weights carefully - Very low weights may frustrate players
Use appropriate rarities - Match rarity to achievement difficulty
Consider duplicates - Set allowDuplicates: false for variety
Test lootbags - Use admin commands to verify contents
Descriptive names - Help players understand what they’re getting