Lite:
Premium:
RareSpawns is a Spigot/Paper plugin that adds fully configurable, data‑driven “rare” entity spawns with unique loot, visual/audio feedback, abilities, and item progression systems. It also provides a standalone custom item framework so you can create collectible, command‑only, or utility items independent of entity spawns.
Table of Contents
- Data‑driven rare entity system (YAML) with spawn groups, weights, biome/time/weather filters.
- Standalone custom items (loot, keys, utilities) with progression features (Soul Harvester).
- Upgrade chain system: attributes, enchantments, model data, lore/name, item model swaps, powers.
- Player‑facing Soul Powers (runtime compiled Java) unlocked through item progression.
- Ability system for rare entities (packaged + extensible runtime compilation).
- Power Items (BREAK, REDSTONE, TROWEL) enabling block manipulation or placement mechanics.
- Integration: WorldGuard, GriefPrevention, mcMMO, Nexo / ItemsAdder / Oraxen (soft).
- Lightweight Java API for detection, ID resolution, programmatic spawns, listings.
- Opt‑out command for players who do not want rares spawning near them.
- Minimal dependencies; only requires Java 21+, a JDK if you use runtime compilation features, and ValorlessUtils.
| Feature | Summary |
|---|---|
| Rare Entities | Weighted spawn selection; configurable loot, attributes, effects, messages, boss bars, minions/abilities. |
| Abilities | Pre‑made behaviors (summon minions, defensive phases, AoE attacks) referenced by ID in YAML. |
| Custom Items | Independent item definitions for loot, commands, or utility tools. |
| Soul Harvester | Items gather “souls” from configured actions to unlock upgrade chains and powers. |
| Soul Powers | Player triggers (onAttack, onDefence, onKill, onEquip) granting effects when unlocked. |
| Power Items | BREAKER, REDSTONE, TROWEL actions with configurable block lists, delays, sounds, permissions. |
| Integrations | Support for custom items/blocks from Nexo, ItemsAdder, Oraxen; respects protection plugins. |
| Opt‑out | Players can disable nearby rare spawns via a command. |
| API | Simple static helpers for other plugins and scripts. |
- Download the plugin JAR and place it in
plugins/. - (Optional) Install integrations: PlaceholderAPI, WorldGuard, GriefPrevention, mcMMO, Nexo/ItemsAdder/Oraxen.
- Start server; plugin creates default config, templates, and example entity/item files.
- Review wiki: RareSpawns Wiki.
- Define spawn groups and globals in
config.yml. - Create or copy entity templates in
plugins/RareSpawns/entities/. - Assign weights, spawn-group, conditions (biomes, time, weather).
- Add drops, equipment, abilities, messages.
- Create custom items in
plugins/RareSpawns/items/. - (Optional) Add
soul-harvestersection for progression features. - Reload with
/rarespawns reloador restart server. - Monitor console logs for successful loads or errors.
| Command | Description | Permission |
|---|---|---|
/rarespawns reload |
Reload configuration & content (abilities/items/entities). | rarespawns.reload |
/rarespawns item <id> [random] |
Give a custom item to self with fixed or random stats. | rarespawns.item |
/rarespawns spawn <id> [player] |
Spawn a rare entity at self/target player. | rarespawns.spawn |
/rarespawns kill <radius> |
Kill rares within radius around sender. | rarespawns.kill |
/rarespawns optout |
Toggle rare spawn opt‑out. | rarespawns.optout |
Key sections inside an entity YAML (see entities/template.yml):
weight,spawn-groupconditions(biomes, whitelist/blacklist, time ranges, weather)type,health,effects,attributesitems(equipment)drop-table(supports chance, ranges, namespaced IDs for external items)abilities(list of ability IDs with optional per-use cooldown override)- Presentation:
name,nameplate,bossbar,spawn-message,death-message - Misc flags: aggro-range, can-despawn, anti-stuck, visibility, variant-specific settings.
Use abilities: list with IDs such as:
spawnbrood(summon spiders)callhive(summon angry bees)curseundead(apply slowness/fire)frostedfur(freeze/slowness on attackers)hardenediron(projectile immunity phase)nightcloak(night invisibility)thornmaw(evoker fang lines)undyingcommander(persistent minion squad + damage transfer)
Syntax:
abilities:
- spawnbrood
- thornmaw:45- Soul Harvester: item section
soul-harvester:defines gain method (KILL, MINING, DEFENCE, FISHING, BUILDING), upgrade chain with thresholds & chance. - Upgrade types: ATTRIBUTE, ENCHANTMENT, POWER, MODELDATA, ITEMMODEL, ITEMNAME, DISPLAYNAME, LORE, LOREADD.
- Soul Powers: unlocked via
POWERupgrade; runtime player effects with triggers & cooldowns. - Requires JDK for runtime compilation if you add custom Soul Powers.
poweritem: section (per item) supporting:
type: BREAKER | REDSTONE | TROWEL- Block allow lists, world filters, consumable flag, sounds.
- TROWEL: hotbar block random selection, delay & durability cost.
- BREAKER: optional drops & ominous state checks.
| Plugin | What RareSpawns Uses |
|---|---|
| Nexo / ItemsAdder / Oraxen | Namespaced item & block IDs, paper note-block data placement (TROWEL). |
| WorldGuard | Build permission checks before PowerItem placement / soulstone spawn. |
| GriefPrevention | Claim “Build” trust checks. |
| mcMMO | Marks blocks placed by PowerItems as ineligible for skill exploitation. |
| PlaceholderAPI | Parses external placeholders (currently no native RareSpawns placeholders). |
Before performing actions (place blocks, spawn via soulstones, use PowerItems) RareSpawns checks registered protection hooks. Actions abort silently if protections fail.
- Supported if installed.
- Currently RareSpawns does not expose its own placeholders; it only parses third‑party placeholders embedded in messages or UI text.
Players can run /rarespawns optout to toggle whether natural rare spawns consider them. If opted out, spawn replacement near that player is skipped.
- Spawn evaluation runs on natural creature spawn events; lightweight filters reduce overhead.
- Minion & ability tasks are periodic; prefer modest counts to avoid entity spam.
- Use staging server to test large upgrade chains or custom code (abilities / powers).
- Runtime compilation only occurs on reload/start for powers/abilities.
| Issue | Check |
|---|---|
| Rares not spawning | Spawn group chance, conditions (biome/time/weather), weight values, opt‑out state. |
| Ability not firing | Correct ID, cooldown not active, rare has a target, no console errors. |
| Soul upgrades not applying | Souls count >= threshold, world whitelist/blacklist, chance <100 may need retries. |
| PowerItem inactive | Correct permission, world allowed, block list matches, delay not too high. |
| Placeholder not parsing | PlaceholderAPI installed & expansion present; RareSpawns only parses external placeholders. |
| Custom power/ability fails | Running a JDK (not JRE), correct filename/class name, no package declaration, server log diagnostics. |
I recommend reading the API Wiki
Static methods (see full docs at API Docs):
// Detection & IDs
RareSpawnsAPI.isRare(entity);
RareSpawnsAPI.isRareItem(itemStack);
RareSpawnsAPI.getRareID(entity);
RareSpawnsAPI.getRareID(itemStack);
// Items
RareSpawnsAPI.getItem(id, randomize);
RareSpawnsAPI.getItemData(id);
RareSpawnsAPI.getItemIds();
// Rares
RareSpawnsAPI.getRare(id);
RareSpawnsAPI.getRareIds();
RareSpawnsAPI.spawnRare(id, location);
// Abilities
RareSpawnsAPI.getAbilityIds();
// Plugin handle
RareSpawnsAPI.getInstance();Synchronous Bukkit events you can listen to:
| Event | Purpose |
|---|---|
RareSpawnEvent |
Fired when a rare entity is spawned (includes SpawnCause). |
RareUpdateEvent |
Fired when a rare is first tracked or refreshed. |
RareDeathEvent |
Fired when a rare dies; includes killer, drops, command kill flag. |
- Implement interfaces (
Ability,SoulPower) & annotate (@AbilityInfo,@SoulPowerInfo). - Place source in data folders (
abilities/orsoulpowers/) default package, no package line. - Requires JDK; server compiles them asynchronously on reload/start.
- Soul Powers: triggers (
onAttack,onDefence,onKill) with chance, cooldown, failCooldown semantics.
ItemDataandEntityDataresolve parsed YAML into runtime properties.- Persistent tags stored in the item/entity via PDC for upgrades, minion flags, souls.
- Upgrade application writes UUID markers & soul power flags.
- Natural spawn event intercepted.
- Filters: spawn reason NATURAL, not swimming/in water, nearest player (opt‑out check).
- Iterate configured spawn groups, roll chance.
- Select entity by weight; verify conditions (biome/time/weather).
- Replace vanilla spawn with rare; apply data & metadata (nameplate, bossbar, attributes).
- Fire
RareSpawnEvent.
- Use RareSpawns API to detect rares & apply custom logic (e.g., specialized rewards).
- Add third‑party item sources (namespaced IDs) to drop tables.
- Wrap Soul Harvester progression for custom reward gating.
- Introduce new runtime powers or abilities for dynamic effects (avoid blocking operations).
Suggestions & issues welcome:
- Propose new upgrade types or powers.
- Submit performance profiling or integration requests.
- When contributing runtime features ensure non-blocking logic (schedule heavy tasks async).
- Native RareSpawns PlaceholderAPI placeholders.
- Additional Soul Power triggers (onEquip refinement, onBlockPlace, onFish success).
- Configurable AI profiles.
- Extended upgrade actions: particle trails, timed buffs, conditional triggers.
- Web-based config viewer/export. (More like wishful thinking atm)
License will be added / clarified (TBD). Until formal license is published, treat source as all-rights-reserved; do not redistribute compiled builds without permission.
For full documentation, examples, and integration guides visit the Docs Site & Wiki Page. Feel free to open issues for feature requests or clarification.
Enjoy crafting your world’s rare encounters!