> 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-wheel-spin.md).

# Addon Wheel Spin

A lucky wheel with a grand prize, pity guarantee, free spin and multi spin. To create a wheel, go to Create > BulletHellTemplate > Addons > Wheel Spin > Wheel Definition.

{% hint style="warning" %}
**Paid addon.** The Lucky Wheel 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 %}

The Lucky Wheel is set up with two kinds of assets:

* **Wheel Definition**: the rules of a wheel (segments, prizes, cost, grand prize odds, free spin, multi spin).
* **Prize Item**: one prize of the wheel.

The screen is the `UILuckyWheel` prefab (`Addons/LuckyWeel/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 example wheel is `Addons/LuckyWeel/Resources/Scriptables/WheelSpinDefinition.asset`, with its prizes in the same folder. The addon works on the three backends.

{% hint style="info" %}
Wheel Definitions must stay in a **Resources** folder: the Offline and Firebase backends load them from there.
{% endhint %}

***

## Wheel Definition

<figure><img src="https://215355839-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fc8AVbPtcUOjcVrQx9Eyu%2Fuploads%2Fgit-blob-deb38d46bba6867ff7a994056cf585524c9f4163%2Fv16-wheel-definition.png?alt=media" alt="Wheel Definition in the Inspector"><figcaption></figcaption></figure>

Wheel Id: Unique id of the wheel (`default`). The spins and the history are saved with it.

Segment Count: Number of segments of the wheel. The screen needs one **Segment Slot** per segment.

Grand Prizes: The big prizes. One of them is the current grand prize, always drawn on the wheel. After a big win another one is chosen.

Common Prizes: The prizes that fill the other segments, in the order of the list.

Reserve Prize: Fills the segments left when there are fewer prizes than segments. It can repeat.

Spin Cost Currency Id / Spin Cost Amount: Currency and price of one spin (the demo uses 1 Diamond). Use a currency that exists in the Game Instance.

Big Win Gacha Rate: Chance, in percent, of landing on the grand prize. The other segments share the rest equally.

Guarantee Big Win After Spins / Spins Until Guaranteed Big Win: The grand prize is forced after this many spins without it (a pity counter).

Free Spin Cooldown Hours: Hours between two free spins (0 = no free spin). A free spin rolls like a paid one and counts for the guarantee.

Multi Spin Count: Spins bought at once by the "SPIN x10" button (maximum 20; 0 or 1 hides the button).

Max History Entries: Entries kept in the history of the wheel.

**Export Wheel Spins to JSON** exports every wheel of the project for the WebSocket server.

## Prize Item

**Create > BulletHellTemplate > Addons > Wheel Spin > Prize Item**.

<figure><img src="https://215355839-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fc8AVbPtcUOjcVrQx9Eyu%2Fuploads%2Fgit-blob-e0e9c6ca3d5c4d58e6af6f543bd31925b5c65b6a%2Fv16-prize-wheel-item.png?alt=media" alt="Prize Item in the Inspector"><figcaption></figcaption></figure>

Prize Id: Unique id of the prize inside its wheel. A prize without an id cannot be won (the spin is refused and nothing is charged).

Title: Name of the prize. Empty uses the name of the reward.

Icon: Icon on the segment. Empty uses the icon of the reward.

Prize Type: **Currency**, **Icon**, **Frame**, **Character** or **Inventory Item**. Fill the field of that type: **Currency** + **Currency Amount**, **Icon Reward**, **Frame Reward**, **Character Reward** or **Inventory Item Reward**.

Unique Per Player: The prize can be won only once; after that it leaves the wheel and the reserve prize takes its place. Turn it off for currency prizes.

***

## Screen

<figure><img src="https://215355839-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fc8AVbPtcUOjcVrQx9Eyu%2Fuploads%2Fgit-blob-0a06bcb58e81ee015a24a5cc417b6fbbcb76c452%2Fv16-wheel-spin-panel.png?alt=media" alt="Wheel Spin Panel in the Inspector"><figcaption></figcaption></figure>

The `UILuckyWheel` prefab shows the wheel set in its **Wheel Definition** field (with the matching **Wheel Id**). If you change **Segment Count**, add or remove **Segment Slots** on the prefab so there is one slot per segment.

***

### On each backend

| Backend             | How it works                                                                                                                                                                                      |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Offline**         | The spin is rolled on the device and saved locally.                                                                                                                                               |
| **Firebase**        | The spin is rolled on the device; the cost, the prize, the wheel state and the history are saved in the player's account in one transaction. No extra rules or indexes are needed.                |
| **WebSocket + SQL** | The server rolls the spin (and multi spins, up to 20 per request), charges the cost and gives the prizes in one transaction, from `wheels.json`. The free spin cooldown is checked on the server. |

For the WebSocket server, export again after every change of prizes, odds or cooldown (button of the Wheel Definition, or **Tools > BulletHellServer > Export All**).

{% hint style="success" %}
A good wheel has a grand prize worth chasing, a guarantee so unlucky players still get it, and a daily free spin to bring players back every day.
{% endhint %}