> For the complete documentation index, see [llms.txt](https://changelog.matrixemulator.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://changelog.matrixemulator.com/welcome/server/muserver/data/event/bonusmanager.md).

# BonusManager

<mark style="color:green;">Temporary and scheduled server bonuses (e.g., double EXP during a weekend or increased Excellent item drop rates on holidays). Supports up to 30 independent bonuses (</mark><mark style="color:green;">`Index`</mark> <mark style="color:green;"></mark><mark style="color:green;">from 0 to 29), each with its own schedule. The file is divided into 3 blocks, each starting with the block number (</mark><mark style="color:green;">`0`</mark><mark style="color:green;">,</mark> <mark style="color:green;"></mark><mark style="color:green;">`1`</mark><mark style="color:green;">, or</mark> <mark style="color:green;"></mark><mark style="color:green;">`2`</mark><mark style="color:green;">) on its own line and ending with</mark> <mark style="color:green;"></mark><mark style="color:green;">`end`</mark><mark style="color:green;">.</mark>

### <mark style="color:yellow;">Section 0 — bonus start schedule</mark>

| Column                                            | Accepted Values     | Description                                                                                                         |
| ------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Index                                             | Number from 0 to 29 | Which bonus this schedule entry belongs to.                                                                         |
| Year / Month / Day / DoW / Hour / Minute / Second | Number or `*`       | A scheduled start time. `*` = any value (cron-style schedule). The same `Index` can have multiple schedule entries. |

### <mark style="color:yellow;">Section 1 — bonus messages and duration</mark>

| Column       | Accepted Values        | Description                                                                                       |
| ------------ | ---------------------- | ------------------------------------------------------------------------------------------------- |
| Index        | Number from 0 to 29    | Which bonus this entry belongs to.                                                                |
| StartMessage | Message number or `*`  | Message broadcast to all players when the bonus starts. `*` = no message.                         |
| FinalMessage | Message number or `*`  | Message broadcast to all players when the bonus ends. `*` = no message.                           |
| BonusTime    | Number, **in seconds** | Bonus duration. Note that this value is in seconds, unlike `BloodCastle.dat`, which uses minutes. |

### <mark style="color:yellow;">Section 2 — bonus effects</mark>

<table data-search="false"><thead><tr><th>Column</th><th>Accepted Values</th><th>Description</th></tr></thead><tbody><tr><td>Index</td><td>Number from 0 to 29</td><td>Which bonus this rule belongs to. The same <code>Index</code> may have multiple entries—all of them are active at the same time while the bonus is running.</td></tr><tr><td>BonusIndex</td><td>Number from 0 to 8 (see table below)</td><td>The type of bonus granted by this entry.</td></tr><tr><td>BonusValue_AL0 / AL1 / AL2 / AL3</td><td>Number</td><td>Bonus value for Free / VIP1 / VIP2 / VIP3. <strong>The meaning of this value depends on the <code>BonusIndex</code></strong>—see the notes.</td></tr><tr><td>ItemIndex</td><td>Item number or <code>*</code></td><td>Restricts the bonus to a specific item. <code>*</code> = any item.</td></tr><tr><td>ItemLevel</td><td>Number or <code>*</code></td><td>Restricts the bonus to a specific item level. <code>*</code> = any level.</td></tr><tr><td>MapNumber</td><td>Map number or <code>*</code></td><td>Restricts the bonus to a specific map. <code>*</code> = any map.</td></tr><tr><td>MonsterClass</td><td>Monster class number or <code>*</code></td><td>Restricts the bonus to a specific monster. <code>*</code> = any monster.</td></tr><tr><td>MonsterLevelMin / MonsterLevelMax</td><td>Number or <code>*</code></td><td>Restricts the bonus by the defeated monster's level. <code>*</code> = no limit on that side.</td></tr></tbody></table>

#### <mark style="color:yellow;">BonusIndex values</mark>

<table data-search="false"><thead><tr><th>BonusIndex</th><th>Bonus Type</th><th>How BonusValue is applied</th></tr></thead><tbody><tr><td>0</td><td>Experience rate</td><td>Percentage added on top of the current value (e.g., <code>50</code> = +50%).</td></tr><tr><td>1</td><td>Master Experience rate</td><td>Percentage added on top of the current value.</td></tr><tr><td>2</td><td>Item drop rate</td><td>Percentage added on top of the current value.</td></tr><tr><td>3</td><td>Normal item drop chance</td><td><strong>Not a simple percentage</strong>—moves the current chance closer to the maximum possible chance by the specified proportion (see notes).</td></tr><tr><td>4</td><td>Excellent item drop chance</td><td>Same behavior as BonusIndex 3.</td></tr><tr><td>5</td><td>Ancient/Set item drop chance</td><td>Same behavior as BonusIndex 3.</td></tr><tr><td>6</td><td>Goblin Points</td><td>Added as a flat value (not a percentage).</td></tr><tr><td>7</td><td>Reset count</td><td>Added as a flat value (not a percentage).</td></tr><tr><td>8</td><td>Master Reset count</td><td>Added as a flat value (not a percentage).</td></tr></tbody></table>

### <mark style="color:yellow;">Notes</mark>

* `BonusValue_AL0`–`AL3` behaves in three different ways depending on the `BonusIndex`. This is hardcoded in the server:
  * `BonusIndex` `0`, `1`, or `2`: **adds a percentage** to the current value (`+50` = 50% more than the current value).
  * `BonusIndex` `3`, `4`, or `5`: **not a regular percentage**—the value moves the current drop chance closer to the maximum possible chance by the specified proportion. High values can result in a much larger increase than a simple "+X%", especially when the current chance is already high, so test carefully before using large numbers.
  * `BonusIndex` `6`, `7`, or `8`: **adds a flat value**, with no percentage involved.
* A single bonus (`Index`) can have multiple entries in Block 2—for example, one entry for **+Experience** and another for **+Normal Item Drop Rate**, both active simultaneously, each with different item, map, or monster filters.
* As in `BloodCastle.dat`, `*` in Block 0 means "any value". If `Day` is `*` and `BonusTime` lasts less than one full day, the bonus can reactivate every day within the scheduled period. This is how you would configure, for example, a bonus that is active throughout the entire month of April: `Month = 4`, `Day = *`, `BonusTime = 86400`.

\ <br>