> 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/concepts/gameplay-loop.md).

# Gameplay loop

RareItemHunter Remaster is built around a hunt -> encounter -> loot -> craft loop.

{% stepper %}
{% step %}

### Boss Eggs Spawn

The plugin can place hidden boss eggs automatically or through admin commands.

Automatic spawning is controlled through:

* `trySpawnBossMinutes`
* `autoEggSpawnChance`
* `bossEggExpiration`
* `bossEggAllowedRegions`

Eggs may be restricted by world and, when WorldGuard is installed, by region.
{% endstep %}

{% step %}

### Players Track Eggs

Players use a Legendary Compass to search for the nearest active egg.

There are two compass tiers:

* `Legendary Compass`: points toward the nearest egg
* `Legendary Compass Enhanced`: points toward the nearest egg and shows distance
  {% endstep %}

{% step %}

### Approaching the Egg Awakens the Boss

When a player with `rareitemhunter.hunter.hatch` gets close enough, the egg awakens into its configured boss.

This behavior is controlled by:

* `autoAwakeningDistance`
* `autoAwakeningTicks`

Admins can bypass forced awakening with:

* `rareitemhunter.admin.bypassautohatch`
  {% endstep %}

{% step %}

### The Boss Fight Begins

Bosses can use:

* base melee damage
* custom armor and weapons
* random skills with per-skill chance
* phase-style events triggered by health thresholds
* either `legacy` or `v2` AI

Bosses can also be configured to:

* despawn after a certain number of player kills
* use custom spawn and skill sounds
* break terrain only in allowed worlds or regions
  {% endstep %}

{% step %}

### Bosses Drop Crafting Currencies

Depending on configuration, bosses can drop:

* Rare Essence
* Dark Matter
* Cursed Diamond
* Legendary Tribute

These drops are defined per boss in `bosses.yml` and globally gated through the `loot` section in `config.yml`.
{% endstep %}

{% step %}

### Players Craft Components and Rare Items

The crafting flow has two layers:

1. Players craft a property component for a rare.
2. They combine that component with a compatible base item to create a rare item.

Examples:

* swords, axes, and bows for `SKILL` rares
* tools for `ENCHANTMENT` rares
* books for `SPELL` rares
* armor pieces for `ABILITY` rares
  {% endstep %}

{% step %}

### Rare Items Consume Costs When Used

Rare effects can consume:

* hunger with `costType: food`
* total experience with `costType: xp`
* money with `costType: money`

The final cost is influenced by:

* the property's `useCost` in `rares.yml`
* `costMultiplier`
* `costLevelIncrement`
  {% endstep %}

{% step %}

### Stats and Broadcasts Keep the System Visible

The plugin can track:

* boss kills
* boss damage
* deaths to bosses
* eggs opened
* best hit and average damage
* clan kill totals when a supported group plugin is active

This data can feed scoreboards, holograms, or menus through PlaceholderAPI.
{% endstep %}
{% endstepper %}