# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://arckytech.gitbook.io/arckys-poke-mart-guide/settings-and-setup-file/bonus-items.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.