> 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/readme.md).

# README

RareItemHunter Remaster is a Paper plugin built around discoverable boss encounters, rare crafting progression, and highly configurable PvE and PvP-adjacent mechanics.

Players hunt hidden boss eggs, awaken custom bosses, collect progression materials, and turn those drops into rare items with active and passive powers.

## Why Server Owners Use It

* Turns boss content into a world event instead of a static summon command
* Ships with a full starter content pack that is already editable
* Supports progression through drops, recipes, cooldowns, and activation costs
* Works for both lightweight survival servers and heavily customized setups
* Exposes placeholders, region rules, and optional integrations for deeper server ecosystems

## Core Loop

The gameplay loop is straightforward:

1. The plugin spawns hidden boss eggs in the world.
2. Players use a Legendary Compass to track them.
3. Getting close awakens the boss.
4. Killing the boss rewards materials used to craft powerful custom items.

## At a Glance

* Hidden boss eggs and timed boss hunts
* 23 preconfigured bosses, all editable in `bosses.yml`
* Boss skills and HP-based boss events
* 32 built-in rare properties across combat, utility, mobility, and harvesting
* Rare item crafting with active and passive properties
* Region-based property restrictions with WorldGuard
* YAML or MySQL stat storage
* PlaceholderAPI placeholders for players, bosses, and server stats
* Optional CombatLogX, EssentialsX, and clan/faction integrations
* Configurable main command label with `/boss` fallback compatibility
* Legendary Compass and Legendary Compass Enhanced recipes
* Persistent active egg saving across normal restarts

## Quick Links

* [Install the Plugin](/rareitemhunter-remaster/installation.md)
* [Launch a Working Setup Fast](/rareitemhunter-remaster/quick-start.md)
* [See the Built-in Content](/rareitemhunter-remaster/configuration/concepts/built-in-content.md)
* [Browse Every Built-in Rare](/rareitemhunter-remaster/configuration/rare-catalog.md)
* [Review the Full Config Reference](/rareitemhunter-remaster/configuration.md)
* [Set Up WorldGuard Rules](/rareitemhunter-remaster/configuration/region-rules.md)
* [Check Commands and Permissions](/rareitemhunter-remaster/configuration/commands.md)
* [Explore Integrations](/rareitemhunter-remaster/configuration/integrations.md)

## Good Fit For

* survival servers that want repeatable world events
* progression-focused servers that want craftable boss loot
* PvP or hybrid servers that need configurable limits on mobility and utility effects
* custom networks that need placeholder, region, or item-system integration

## Documentation Tour

* [Gameplay Loop](/rareitemhunter-remaster/configuration/concepts/gameplay-loop.md)
* [Built-in Content](/rareitemhunter-remaster/configuration/concepts/built-in-content.md)
* [Quick Start](/rareitemhunter-remaster/quick-start.md)
* [Commands](/rareitemhunter-remaster/configuration/commands.md)
* [Permissions](/rareitemhunter-remaster/configuration/permissions.md)
* [Placeholders](/rareitemhunter-remaster/configuration/placeholders.md)
* [Rare Catalog](/rareitemhunter-remaster/configuration/rare-catalog.md)
* [Configuration Overview](/rareitemhunter-remaster/configuration/overview.md)
* [Full Config Reference](/rareitemhunter-remaster/configuration/config-reference.md)
* [Boss Definitions](/rareitemhunter-remaster/configuration/bosses.md)
* [Region Rules](/rareitemhunter-remaster/configuration/region-rules.md)
* [Integrations](/rareitemhunter-remaster/configuration/integrations.md)
* [FAQ](/rareitemhunter-remaster/faqs.md)

## Requirements

* Paper `1.21.x`
* Tested on `1.21.11`
* Java `21`

## Optional Dependencies

* EssentialsX
* WorldGuard and WorldEdit
* PlaceholderAPI
* CombatLogX
* CubeClans, SimpleClans, ImprovedFactions, FactionsUUID, or Saber-Factions

All optional integrations disable themselves cleanly when the dependency is not present.

## First Read Path

If this is your first time with the plugin, read in this order:

1. [Installation](/rareitemhunter-remaster/installation.md)
2. [Quick Start](/rareitemhunter-remaster/quick-start.md)
3. [Built-in Content](/rareitemhunter-remaster/configuration/concepts/built-in-content.md)
4. [Config Reference](/rareitemhunter-remaster/configuration/config-reference.md)
5. [Commands](/rareitemhunter-remaster/configuration/commands.md)

## Audience

This documentation is written for:

* server owners configuring the plugin for production
* admins who need command and permission reference
* builders balancing bosses, recipes, and progression
* developers integrating custom item systems or craft hooks