> For the complete documentation index, see [llms.txt](https://arckytech.gitbook.io/arckys-poke-mart-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://arckytech.gitbook.io/arckys-poke-mart-guide/settings-and-setup-file/bonus-items.md).

# Bonus Items

This is a new feature as of v1.3.0 of the Poké Mart Plugin. It allows you to setup Bonus Items for multiple Items. 

Bonus Items apply to all stores for the same Item.

A Bonus Item is only given if the bought Item is found in the `BonusItems` Setting.

***

### Example 1

This is the basic structure where you give the amount required to get the bonus item given.

```ruby
BonusItems = {
  :POKEBALL => {
    :amount => 10,
    :item => :PREMIERBALL
  }
}
```

* `:POKEBALL => { }` = the Item's ID that can give bonus Items followed by a Hash.
  * `:amount => 10` = for each 10 bought Poke Balls, you'll get a Bonus Item.
  * `:item => :PREMIERBALL` = The Bonus Item's ID.

So to conclusion: For each 10 bought Poke Balls, you'll be given 1 Premier Ball. 

{% hint style="info" %}
Only for Item Balls, if the bought Item is a Great Ball or any kind of Ball Item, this bonus Item will be applied unless you added a specific Bonus Item for that Ball Item.
{% endhint %}

***

### Example 2

This is an expansion on the structure from example 1 where you can give an array of multiple items along with (optional) a specific chance for this item to be chosen as the given bonus item.

```ruby
BonusItems = {
  :GREATBALL => {
    :amount => 10,
    :item => [
      [:GREATBALL, 20],
      :PREMIERBALL
    ]
  }
}
```

* `:GREATBALL => { }` = the item's ID that can give bonus Items followed by a Hash.
  * `:amount => 10` = for each 10 bought Great Balls, you'll get a Bonus Item.
  * `:item => [ ]` = an **array** containing items.
    * `[:GREATBALL, 20]` = an array containing the following:  
      * `:GREATBALL` = the Bonus Item's ID.
      * `20` = the chance this Bonus Item is given. (optional).
    * `:PREMIERBALL` = the Bonus Item's ID. (There's no chance given so the remaining chance is 80%)

So to conclusion: For each 10 bought Great Balls, you'll be given either a Great Ball (20% chance) or a Premier Ball (80% chance).

{% hint style="info" %}
For the Bonus Items that don't have a chance, the remaining chance will be devided among them. 
{% endhint %}

***

### Example 3

This is the most complex structure and is used if you want to give more than 1 of the bonus item for the required amount of the bought item. You can also give a chance like in example 2.

<pre class="language-ruby"><code class="lang-ruby">BonusItems = {     
<strong>  :ULTRABALL => {
</strong>    :amount => 5,
    :item => {
      :PREMIERBALL => {
        :amount => 3
      },
      :MASTERBALL => { 
        :chance => 0.1 
      },
      :ULTRABALL => {
        :amount => 2,
        :chance => 5
      }
    }
  }
}
</code></pre>

* `:ULTRABALL => { }` = the item's ID that can give the bonus items followed by a Hash.
  * `:amount => 5` = For each 5 bough Ultra Balls, you'll get a Bonus Item.
  * `:item => { }` =  A **hash** containing items.
    * `:PREMIERBALL => { }` = The Bonus Item's ID followed by a hash.
      * `:amount => 3` = The amount of this Bonus Item you get for each 5 Ultra Balls.
    * `:MASTERBALL => { }` = The Bonus Item's ID followed by a hash.
      * `:chance => 0.1` = The chance (0.1%) this Bonus Item is given.&#x20;
    * `:ULTRABALL => { }` = The Bonus Item's ID followed by a hash.
      * `:amount => 2` = The amount of this Bonus Item you get for each 5 Ultra balls.
      * `:chance => 5` = The chance (5%) this Bonus Item is given.

{% hint style="warning" %}
If you are using this structure then either :amount or :chance must be given for each Bonus Item, if you don't give any of these then you should use the structure of Example 2 instead.
{% endhint %}