> For the complete documentation index, see [llms.txt](https://bizachi-dev.gitbook.io/bullethell-elemental-template/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bizachi-dev.gitbook.io/bullethell-elemental-template/paid-addons/addon-lootbox-v1.5.md).

# Addon Lootbox

To create a LootboxItem, right-click inside any project folder, go to Create > BulletHellTemplate > Addons > Lootbox > Lootbox Item.

{% hint style="warning" %}
**Paid addon.** The Loot Box addon is not included in the BulletHell Elemental Template. It is sold separately on the Unity Asset Store. This page explains how to set it up after you buy and import it.
{% endhint %}

Loot boxes are opened with a key currency and give a random prize by rarity (Common, Uncommon, Rare, Epic, Legendary). The addon works on the three backends.

The screen is the `UILootboxMenu` prefab (`Addons/LootBox/UIElements`). Add the prefab to the **Canvas** of the Home scene and make a main menu button activate it (in the button On Click, drag the prefab object and choose `GameObject.SetActive`, checked). Also add it to the **Covering Menus** of the Hide Behind Menus components (see [Home Scene](/bullethell-elemental-template/user-interface-menus/home-scene.md)). The addon ships four example boxes in `Addons/LootBox/LootboxItem`: Stone, Hero, Royal and Golden.

***

### 1. Create the key currency

Each box is opened with its own currency (its "key"). If the player has 10 of that currency, they have 10 boxes. The example keys are the currencies `STN`, `HERO`, `ROYAL` and `GOLDEN` in `Addons/LootBox/CurrencyBox`. Add them (or your own keys, created like any [currency](/bullethell-elemental-template/scriptables/create-new-currency.md)) to **Game Instance > Currency Data**.

Players get keys from the shop, quests, the battle pass, daily rewards or the wheel.

### 2. Create the Lootbox Item

<figure><img src="https://215355839-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fc8AVbPtcUOjcVrQx9Eyu%2Fuploads%2Fgit-blob-3881437551801b0e63dbac6288c55f1280607940%2Fv16-lootbox-item.png?alt=media" alt="Lootbox Item in the Inspector"><figcaption><p>Golden Box.</p></figcaption></figure>

**Identity**

Lootbox Id: Unique id of the box (for example `golden_box`). The backends find the box by this id.

Title / Description (and their translations): Texts of the box.

**Cost**

Currency Id: Coin ID of the key currency.

Price: Keys spent per open (at least 1).

**Icons**

Menu Icon: Icon in the list.

Closed Icon / Opened Icon: The box while it shakes, and when the prize is revealed.

**Look**

Accent Color: Color of the glow and rays behind the box. With the alpha at 0 the color of the rarest rarity the box can drop is used.

**Rarity Chances (weights)**

Common / Uncommon / Rare / Epic / Legendary Chance: Weight of each rarity. The real chance is the weight divided by the sum of the five, so keep the sum at 100 to read them as percentages.

**Rules**

Skip Owned Cosmetics: Icons and frames the player already owns are left out of the roll, so a cosmetic is never won twice. If a rarity has nothing left, the roll falls back to Common; a box with nothing left at all cannot be opened (nothing is charged).

**Rarity Pools**

Common / Uncommon / Rare / Epic / Legendary Items: The prizes of each rarity: **Currency Prizes** (currency + amount), **Frames**, **Icons** and **Inventory Items**. When a rarity is rolled, one prize of its pool is picked at random. A rarity with an empty pool uses the Common pool.

### 3. Add the box to the screen

Select the `UILootboxMenu` object in the Home scene (or the prefab) and add the box to **Lootboxes > Lootbox Items**. The list order is the order on screen.

<figure><img src="https://215355839-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fc8AVbPtcUOjcVrQx9Eyu%2Fuploads%2Fgit-blob-772fdf8b888a8df40d36d4e89fcce952277e6187%2Fv16-ui-lootbox-panel.png?alt=media" alt="UI Lootbox Panel in the Inspector"><figcaption></figcaption></figure>

The other groups of the panel control the look: the confirm dialog, the odds popup (shows the chances of each rarity), the box animation and opening effects, the reward popup and their texts.

{% hint style="warning" %}
On the Offline and Firebase backends the box data is read from this list, so a box that is not in **Lootbox Items** cannot be opened.
{% endhint %}

***

### On each backend

| Backend             | How it works                                                                                                                                                   |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Offline**         | The roll happens on the device and the prize is saved locally.                                                                                                 |
| **Firebase**        | The roll happens on the device and the key and the prize are saved in the player's account in one transaction. No extra rules or indexes are needed.           |
| **WebSocket + SQL** | The server rolls the prize, charges the key and gives the prize in one database transaction, from `lootboxes.json`. A repeated request is never applied twice. |

For the WebSocket server, export the boxes with the **Export Lootboxes to JSON** button of the panel, or with **Tools > BulletHellServer > Export All** (see [Exporting Game Data](/bullethell-elemental-template/getting-started/exporting-game-data.md)), and send them to the server. Export again after every change of chances or prizes.