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

# Config Reference

This page is a more complete reference for `config.yml`.

## General

| Key                            | Description                                                                                  |
| ------------------------------ | -------------------------------------------------------------------------------------------- |
| `debug`                        | Enables verbose runtime debugging for properties, cooldowns, lore parsing, and region checks |
| `itemBridgeDebug`              | Enables extra debug logging for external item bridge and dynamic crafting logic              |
| `commands.main`                | Configures the preferred main command label shown to players                                 |
| `handle-player-death-messages` | Lets the plugin override boss-related player death messages                                  |
| `language`                     | Selects `language_en.yml` or `language_es.yml`                                               |
| `groups.provider`              | Selects or disables clan/faction integration                                                 |
| `update-notifications`         | Notifies admins with `rareitemhunter.admin.notify` about updates                             |
| `metrics-enabled`              | Enables or disables bStats telemetry                                                         |

## Boss Egg Auto Generation

| Key                     | Description                                                    |
| ----------------------- | -------------------------------------------------------------- |
| `trySpawnBossMinutes`   | Minutes between automatic egg spawn attempts; `-1` disables it |
| `autoEggSpawnChance`    | Percent chance for each automatic spawn attempt to succeed     |
| `bossEggExpiration`     | Minutes before an auto-spawned egg disappears                  |
| `autoAwakeningDistance` | Distance at which eligible players awaken eggs                 |
| `autoAwakeningTicks`    | Tick interval used to check nearby players                     |

## Random Placement

| Key                         | Description                                                   |
| --------------------------- | ------------------------------------------------------------- |
| `bossEggAllowedRegions`     | Allowed worlds and WorldGuard regions for random egg spawning |
| `randomEggRadius`           | Horizontal radius used for random spawn search                |
| `randomEggAttemptsPerWorld` | Candidate attempts per world before trying another            |
| `defaultRandomEggWorld`     | Fallback world for random egg commands                        |
| `defaultRandomEggRegion`    | Fallback region for random egg commands                       |
| `defaultRandomEggCords`     | X,Z center point used for random placement                    |

## Boss Behavior

| Key                            | Description                                                       |
| ------------------------------ | ----------------------------------------------------------------- |
| `bossExpireKills`              | Remove a boss after it kills enough players; `-1` disables this   |
| `bossDisappearSound`           | Sound played when a boss leaves after reaching the fury limit     |
| `disableCreativeGodOnFight`    | Forces players into normal combat conditions when fighting bosses |
| `bossAI.defaultMode`           | Global AI mode: `legacy` or `v2`                                  |
| `bossAI.v2.targetUpdateTicks`  | How often V2 bosses reevaluate targets                            |
| `bossAI.v2.targetRange`        | Max distance for V2 target searching                              |
| `regionsWhereBossesCanDestroy` | Allowed worlds and regions for terrain damage                     |

## Notifications and Sounds

| Key                         | Description                                          |
| --------------------------- | ---------------------------------------------------- |
| `notificationMode`          | `chat`, `title`, or `title+chat`                     |
| `compassNotificationMode`   | `chat` or `actionbar`                                |
| `defaultEggAppearSound`     | Sound for egg appearances                            |
| `eggAppearSoundPermission`  | Permission required to hear egg-appearance sounds    |
| `defaultBossAwakeningSound` | Fallback spawn sound for bosses without a custom one |

## Loot and Recipes

| Key                                  | Description                                      |
| ------------------------------------ | ------------------------------------------------ |
| `legendaryCompassRecipe`             | 3x3 recipe for the Legendary Compass             |
| `legendaryCompassEnhancedRecipeType` | `shaped` or `shapeless` for the enhanced compass |
| `legendaryCompassEnhancedRecipe`     | Recipe for the enhanced compass                  |
| `loot.rare_essences`                 | Enable or disable Rare Essence boss drops        |
| `loot.dark_matter`                   | Enable or disable Dark Matter boss drops         |
| `loot.cursed_diamonds`               | Enable or disable Cursed Diamond boss drops      |
| `loot.legendary_tributes`            | Enable or disable Legendary Tribute boss drops   |

Notes:

* The enhanced compass recipe still requires a full 3x3 crafting table even in shapeless mode.
* Recipe tokens support both normal materials and special plugin item keys.

## Cost System

| Key                  | Description                                   |
| -------------------- | --------------------------------------------- |
| `costType`           | Activation resource: `food`, `xp`, or `money` |
| `costLevelIncrement` | Extra scaling based on item level             |
| `costMultiplier`     | Global multiplier applied to property costs   |

## Restricted Worlds

| Key                                      | Description                                       |
| ---------------------------------------- | ------------------------------------------------- |
| `RestrictedWorld1` to `RestrictedWorld3` | Worlds where `ENCHANTMENT` properties are blocked |

This only affects enchantment-style rares such as harvesting and tool effects.

## Stats Storage

| Key                 | Description                                   |
| ------------------- | --------------------------------------------- |
| `statsStorage`      | `yaml`, `mysql`, `off`, `none`, or `disabled` |
| `mysql.host`        | MySQL host                                    |
| `mysql.port`        | MySQL port                                    |
| `mysql.database`    | Database name                                 |
| `mysql.username`    | Database username                             |
| `mysql.password`    | Database password                             |
| `mysql.tablePrefix` | Prefix for plugin tables                      |

The plugin falls back to YAML if MySQL initialization fails.

## CombatLogX

| Key                               | Description                                           |
| --------------------------------- | ----------------------------------------------------- |
| `combatLogX.tagOnBossCombat`      | Tags players during boss combat                       |
| `combatLogX.announceLogoutPunish` | Broadcasts punishments for combat logging near bosses |
| `combatLogX.blockedProperties`    | Per-property allow or deny map while combat tagged    |

## World Aliases

Public boss and egg announcements can show friendly world labels through `world_aliases.yml`.

Example:

```yaml
world: "/warp survival"
world_nether: "/warp nether"
world_the_end: "/warp end"
```

If a world is not listed, the plugin shows the real Bukkit world name.