LootBox

LootBox

Open mysterious boxes and receive fully configurable rewards, with adjustable chances, amounts, and item quality. Perfect for servers looking to create progression systems, treasure events, or custom rewards in Valheim.

Features

• Fully Configurable

Define custom drop tables directly in the configuration file, supporting individual chances, quantity ranges, and item quality.

• Independent Chances System

Each item has its own independent drop chance.

• Server-Synced

All configurations are synchronized via ServerSync, ensuring consistent behavior across all players.

• Modular Integration

The mod does not automatically drop from creatures. It is designed to work together with other loot systems such as Drop That!

Configuration

• Automatic creation of folder and template file

On first initialization, the mod automatically creates the LootBox folder inside BepInEx/config, along with a template configuration file to serve as a starting point. (This is only generated on server and single-player environments; it is not generated on clients.)

• Definitions via CFG files

Lootboxes are configured through external .cfg files inside the BepInEx/config/LootBox folder, keeping the setup cleaner and easier to maintain.

• File naming

Configuration files use this pattern: radamanto.LootBox.<anything>.cfg

• Multiple files supported

You can split your lootboxes across multiple different files, and each file can contain multiple lootbox definitions, as long as they are placed inside the LootBox folder and follow the expected naming pattern.

• One section per lootbox prefab

Each lootbox must be declared using the prefab name as the section header. Do not configure the same lootbox twice. Example: [rd_gold_lootbox_01]

• Reward line format

Each line inside the section represents one possible reward, using this format: Item=Chance,Amount,Quality

• Fixed amount or range

The amount field supports both fixed values and ranges: 5 = fixed amount 50-100 = random amount between 50 and 100

• Examples of valid configurations

  [rd_gold_lootbox_01]
  Coins=100,50-100,1
  Ruby=50,5,1
  SwordSilver=50,1,2

  [rd_gold_lootbox_02]
  Iron=100,25-50,1
  SwordBlackmetal=35,1,3
  ShieldBlackmetal=20,1,2

  [rd_gold_lootbox_03]
  Resin=100,10-30,1
  FreezeGland=40,3-8,1
  BowHuntsman=25,1,2

- **Example explanation**  
  `Coins=100,50-100,1` → 100% chance, amount between 50 and 100, quality 1  
  `Ruby=50,5,1` → 50% chance, fixed amount 5, quality 1  
  `SwordSilver=50,1,2` → 50% chance, amount 1, quality 2

- **Important**  
  The section name must match the lootbox prefab exactly.  
  The item name must also match the item's internal in-game name exactly.  
  
## Translations

- **YML translation file included**  
  A `.yml` translation file is included with the plugin.

- **Custom lootbox names per language**  
  Through this file, the names of the lootboxes can be changed or translated to the desired language.

- **Simple language customization**  
  You can define custom display names for each lootbox, making it easier to adapt the mod to your server, modpack, or community language.

- **Intended for display names**  
  This translation file is intended to control how lootbox names are shown to players in-game.

## Administration Command

- **Configuration reload**  
  The `lootbox.reload` command forces a reload of the `.cfg` files in `BepInEx/config/LootBox`.

- **Runtime reapplication**  
  Valid definitions are reloaded and reapplied without restarting the game or server.

- **Restricted usage**  
  This command is restricted to administrators.
  
## Global Opening Effects

- **Configurable opening effects**  
  The mod allows switching between different global visual and sound effects for lootbox opening.

- **Global behavior**  
  The selected effects are applied globally to all lootboxes.

- **Visual and sound selection**  
  You can choose which visual effect and which sound effect will be used during box opening through the plugin configuration.  

## How to Use

To open a **Loot Box**, simply **hold SHIFT and right-click** the item in your inventory.  
When you do this, the box will be **consumed**, and its rewards will be **placed into your inventory**.  
If any reward cannot fit in the inventory, the **excess will be dropped on the ground**.

![](https://i.imgur.com/TW7TDF9.png)
  
  ## Installation (manual)

- Place **LootBox.dll** inside your `BepInEx\plugins\` folder.

<details>
  <summary><b>Prefabs Lootboxes</b> (<i>click to expand</i>)</summary>
  <br/>

| prefab | name |
|------|------|
| rd_gold_lootbox_01 | Golden Box 1 |
| rd_gold_lootbox_02 | Golden Box 2 |
| rd_gold_lootbox_03 | Golden Box 3 |
| rd_gold_lootbox_04 | Golden Box 4 |
| rd_gold_lootbox_05 | Golden Box 5 |
| rd_gold_lootbox_06 | Golden Box 6 |
| rd_gold_lootbox_07 | Golden Box 7 |
| rd_gold_lootbox_08 | Golden Box 8 |
| rd_gold_lootbox_09 | Golden Box 9 |
| rd_gold_lootbox_10 | Golden Box 10 |
| rd_silver_lootbox_01 | Silver Box 1 |
| rd_silver_lootbox_02 | Silver Box 2 |
| rd_silver_lootbox_03 | Silver Box 3 |
| rd_silver_lootbox_04 | Silver Box 4 |
| rd_silver_lootbox_05 | Silver Box 5 |
| rd_silver_lootbox_06 | Silver Box 6 |
| rd_silver_lootbox_07 | Silver Box 7 |
| rd_silver_lootbox_08 | Silver Box 8 |
| rd_silver_lootbox_09 | Silver Box 9 |
| rd_silver_lootbox_10 | Silver Box 10 |
| rd_bronze_lootbox_01 | Bronze Box 1 |
| rd_bronze_lootbox_02 | Bronze Box 2 |
| rd_bronze_lootbox_03 | Bronze Box 3 |
| rd_bronze_lootbox_04 | Bronze Box 4 |
| rd_bronze_lootbox_05 | Bronze Box 5 |
| rd_bronze_lootbox_06 | Bronze Box 6 |