> For the complete documentation index, see [llms.txt](https://epyk.gitbook.io/epyk-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://epyk.gitbook.io/epyk-docs/pyplugins/pymobcoins/config.md).

# Config

Configure pyMobCoins in `config.yml`.

This file controls shops, rewards, notifications, menus, sounds, and metrics.

### General settings

<table data-search="false"><thead><tr><th>Setting</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><code>general.main_shop</code></td><td>Shop opened by <code>/mobcoins</code> without arguments.</td><td><code>main</code></td></tr><tr><td><code>general.excluded_worlds</code></td><td>Worlds where mob kills cannot award MobCoins.</td><td>Includes <code>world_the_nether</code></td></tr><tr><td><code>general.earnings_summary_interval</code></td><td>Minutes between periodic earnings summaries.</td><td><code>3</code></td></tr><tr><td><code>general.enable_actionbar_by_default</code></td><td>Enables ActionBar gain messages for new players.</td><td><code>true</code></td></tr><tr><td><code>general.enable_summary_by_default</code></td><td>Enables periodic summaries for new players.</td><td><code>true</code></td></tr><tr><td><code>general.log_transactions</code></td><td>Logs coin grants and purchases to the console.</td><td><code>false</code></td></tr><tr><td><code>general.max_multiplier</code></td><td>Highest personal multiplier administrators can assign.</td><td><code>10</code></td></tr></tbody></table>

Keep `general.log_transactions` disabled unless you need transaction debugging.

Multipliers accept whole numbers only.

### Sounds

Use valid Bukkit or Paper sound enum names.

| Setting                         | When it plays              | Default                  |
| ------------------------------- | -------------------------- | ------------------------ |
| `sounds.shop_refresh_sound`     | A rotating shop refreshes. | `ENTITY_PLAYER_LEVELUP`  |
| `sounds.purchase_success_sound` | A shop purchase succeeds.  | `BLOCK_NOTE_BLOCK_PLING` |
| `sounds.purchase_fail_sound`    | A shop purchase fails.     | `BLOCK_NOTE_BLOCK_BASS`  |

### Coin rewards

Configure mob rewards under `coin_rewards.entity_rewards`.

Each key uses a Bukkit `EntityType` name, such as `ZOMBIE` or `CREEPER`.

```yaml
coin_rewards:
  entity_rewards:
    ZOMBIE:
      amount: 1
      chance: 8
```

| Option   | Description                            |
| -------- | -------------------------------------- |
| `amount` | MobCoins awarded before multipliers.   |
| `chance` | Percentage chance to grant the reward. |

An `8` chance gives an 8% reward chance. The configured amount applies first.

Default rewards include `ZOMBIE`, `SKELETON`, `CREEPER`, and `ENDERMAN`.

For example, `amount: 2` and `chance: 5` gives a 5% chance of two coins.

### Interface settings

The `interface` section controls feedback items and the bulk purchase menu.

#### Feedback items

| Setting                                       | When it appears                 | Options                                      | Default material |
| --------------------------------------------- | ------------------------------- | -------------------------------------------- | ---------------- |
| `interface.feedback_items.insufficient_funds` | A player lacks MobCoins.        | `material`, `base64`, `display_name`, `lore` | `PLAYER_HEAD`    |
| `interface.feedback_items.purchase_complete`  | A purchase succeeds.            | `material`, `base64`, `display_name`, `lore` | `PLAYER_HEAD`    |
| `interface.feedback_items.out_of_stock`       | A rotating reward has no stock. | `material`, `display_name`, `lore`           | `BARRIER`        |

The `out_of_stock` lore supports:

* `{ITEM}` — reward or item name.
* `{AMOUNT}` — requested purchase amount.
* `{STOCK}` — remaining stock.

Use valid Bukkit or Paper material names for `material`.

#### Mass purchase menu

Configure bulk-purchase quantity selection under `interface.mass_purchase_menu`.

| Setting | Description                                | Default               |
| ------- | ------------------------------------------ | --------------------- |
| `title` | Inventory title for the quantity selector. | `&8Quantity Selector` |
| `rows`  | Inventory rows in the selector.            | `5`                   |

**Decorations**

Configure decorative and utility items under `interface.mass_purchase_menu.decorations`.

| Item            | Description                         | Options                                              |
| --------------- | ----------------------------------- | ---------------------------------------------------- |
| `outer_frame`   | Main frame around the menu.         | `material`, `display_name`, `slots`                  |
| `corner_marks`  | Accent markers in menu corners.     | `material`, `display_name`, `slots`                  |
| `wallet_view`   | Shows the player's current balance. | `material`, `base64`, `display_name`, `lore`, `slot` |
| `return_button` | Returns the player to the shop.     | `material`, `display_name`, `lore`, `slot`           |

The `wallet_view` lore supports `{BALANCE}` for the current MobCoins balance.

**Purchase amounts**

Map each inventory slot to its purchase quantity.

```yaml
interface:
  mass_purchase_menu:
    purchase_amounts:
      10: 1
      11: 2
      12: 4
      13: 8
      14: 16
      15: 24
      16: 32
      19: 48
      20: 64
```

Each key is an inventory slot. Each value is the clicked purchase quantity.

{% hint style="warning" %}
Do not overlap decoration slots with purchase amount slots.
{% endhint %}

Items with `bulk_buy` disabled never open this menu.

### Metrics

| Setting           | Description                             | Default |
| ----------------- | --------------------------------------- | ------- |
| `metrics.enabled` | Enables anonymous bStats usage metrics. | `true`  |

bStats collects basic plugin usage statistics. It does not collect personal player data.

### PlaceholderAPI

When PlaceholderAPI is installed, pyMobCoins exposes live values for balances, multipliers, events, and shop refreshes.

See [Placeholders](/epyk-docs/pyplugins/pymobcoins/placeholders.md) for the full reference.

### Notes

* Excluded worlds never award MobCoins from mob kills.
* Reward chances use percentages.
* Rewards are calculated before personal multipliers.
* Mob names must use Bukkit `EntityType` names.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://epyk.gitbook.io/epyk-docs/pyplugins/pymobcoins/config.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.