Back to Tools

NotEnoughRelics Documentation

Welcome to the NotEnoughRelics documentation. Learn how to configure custom artifacts, set up passive modifiers, and bind commands to player events.

📝 YAML Configuration

All items must be configured under the relics: key in your plugin files. Use the sidebar to navigate through the available configuration blocks.

Core Features

Stats & Attributes: Apply static modifiers like Max Health, Strength, Luck, and Movement Speed.
Utility Mechanics: Configure i-frames, double jumps, fall damage reduction, and reach extensions.
Event Triggers: Execute console commands, sounds, and particles reacting to damage, kills, equipping, or ticks.
Loot & Generation: Integrate relics into vanilla structure chests and custom mob drops.
Relic Sets: Link multiple relics to provide massive bonuses when equipped together.

Basic Structure

Every relic relies on a foundational YAML structure defining its visual presence, metadata, and tier.

relics:
  my_custom_relic:
    name: "&eMy Custom Relic"
    material: ENCHANTED_BOOK
    glint: false
    lore:
      - "&7A properly formatted artifact."
    slots:
      - RING
    tier: COMMON
    glow:
      enable: true
      color: "#E2B640"
    custom_model_data: 4310002

Required Keys

Key	Description
`name`	The display name of the item. Supports color codes (&).
`material`	The Bukkit Material type (e.g., `ENCHANTED_BOOK`, `LEATHER_HELMET`).
`glint`	Toggles the vanilla enchantment glint.
`slots`	List of valid equipment slots (e.g., `RING`, `HELMET`, `CLOAK`, `GLOVES`, `BELT`, `NECKLACE`, `RELICS`).
`tier`	Item rarity tier (e.g., `COMMON`, `UNCOMMON`, `RARE`, `EPIC`, `LEGENDARY`, `MYTHIC`).
`glow`	Custom glowing effect configuration. Set `enable: true` and specify a HEX `color`.
`custom_model_data`	Integer value used to assign custom textures via resource packs.

Attributes & Stats

Passive attributes modify player stats while the relic is equipped in its designated slot.

💡 Stacking Attributes

You can stack multiple attributes on a single relic. Just list all desired stat keys under the attributes: block.

The `attributes` Block

Define stat modifications under the attributes: section:

attributes:
  max_health: 4.0
  luck: 2.0
  speed: 1.0
  strength: 3.0
  knockback_resistance: 5.0

Available Attributes

Attribute	Description	Format
`max_health`	Increases maximum health (1.0 = half a heart).	Float (e.g., `6.0`)
`luck`	Increases the generic luck stat.	Float (e.g., `4.0`)
`speed`	Increases movement speed.	Float (e.g., `0.2`)
`strength`	Increases melee damage output.	Float (e.g., `5.0`)
`knockback_resistance`	Reduces incoming knockback.	Float (e.g., `10.0`)

Special Effects & Mechanics

Enhance your relics with continuous potion buffs and unique utility mechanics like invulnerability frames and extra jumps.

Permanent Potion Effects

Use the potion_effects block to apply vanilla Minecraft potion effects that remain active as long as the player has the relic equipped. The number represents the amplifier of the effect (where 0 = Level 1, 1 = Level 2, etc.).

potion_effects:
  SPEED: 0
  INCREASE_DAMAGE: 1
  FIRE_RESISTANCE: 0

Important

You must use standard Bukkit/Spigot PotionEffectType names. For example, use INCREASE_DAMAGE instead of Strength, and SLOW_DIGGING instead of Mining Fatigue.

Utility Special Effects

Use the special_effects block to add custom utility mechanics, such as reach extensions and extra mobility.

special_effects:
  invulnerability_time: 0.5
  fall_damage_reduction: 0.3
  entity_range: 1.5
  block_range: 2.0
  double_jump: 1

Available Mechanics

Key	Description
`invulnerability_time`	Grants extra seconds of i-frames (invulnerability) after the player is hit (e.g., `0.8`).
`fall_damage_reduction`	Reduces incoming fall damage by a percentage (e.g., `0.3` = 30% reduction).
`entity_range`	Increases the player's attack reach against entities (in blocks).
`block_range`	Increases the player's block breaking and interaction reach (in blocks).
`double_jump`	Grants extra mid-air jumps. Accepts integer values (e.g., `1` for one extra jump).

Commands & Triggers

The commands block allows relics to listen for specific player events (like taking damage or killing mobs) and execute console commands, play sounds, or spawn particles.

⚠️ Using Placeholders

Pass dynamic player data into commands using %player_name%, %player_x%, %player_y%, and %player_z%.

Event Listeners

Each listener requires a list of commands and a probability variable ([event]-chance) ranging from 0.0 to 1.0.

onEquip: Triggers when the item is slotted.
onUnequip: Triggers when the item is unslotted.
onKill: Triggers upon killing an entity.
onDeath: Triggers upon player death.
onDamage: Triggers upon taking damage.
onDamageDealt: Triggers upon dealing damage.
onInterval: Triggers repeatedly based on defined interval-ticks.

Configuration Example

commands:
  command-feedback: false

  onKill:
    - "playsound minecraft:entity.experience_orb.pickup player %player_name% %player_x% %player_y% %player_z% 1 2"
    - "particle minecraft:note %player_x% %player_y% %player_z% 1 1 1 1 15"
  onKill-chance: 0.5

  onInterval:
    - "particle minecraft:enchant %player_x% %player_y% %player_z% 0.5 1 0.5 0 5"
  onInterval-chance: 0.1
  interval-ticks: 60

Structure Loot Generation (loot.yml)

You can configure relics to spawn naturally inside vanilla Minecraft structure chests (like Dungeons, End Cities, or Bastions) using the structures section in your loot configuration.

🎲 How the RNG Works (Two-Step Roll)

The system uses a robust two-step roll for fairness:
1. Weight: The plugin picks a random item from the pool based on its weight relative to others.
2. Individual Chance: Once an item is picked, it must pass its own specific chance (e.g., 0.5 = 50%) to actually spawn. If it fails, nothing spawns for that attempt.

Configuration Example

Add this to your loot configuration file:

structures:
  "minecraft:chests/simple_dungeon":
    enabled: true
    min_amount: 1
    max_amount: 3
    pool:
      golden_ring_advanced:
        weight: 10
        chance: 0.5
      mystic_orchestra:
        weight: 2
        chance: 0.1

Understanding the Keys

Key	Description
`"minecraft:..."`	The exact vanilla loot table key (e.g., `minecraft:chests/end_city_treasure`).
`min_amount / max_amount`	The number of generation "attempts" the plugin will make when a chest is opened.
`pool`	The list of your custom `relic_ids` that can potentially spawn in this structure.
`weight`	How heavily weighted this relic is compared to others in the pool. (Higher = More likely to be chosen).
`chance`	The final probability of the item dropping once selected (0.0 to 1.0). Defaults to 1.0 (100%) if not set.

Mob Drops (loot.yml)

Relics can be configured to drop when a player kills specific entities. This system uses the same Weight + Individual Chance system as structures, ensuring balanced drop rates.

⚠️ Player Kills Required

To prevent infinite farming exploits, mobs will only drop relics if the entity was directly killed by a Player. Environmental damage or other mobs will not trigger the drop.

Configuration Example

Define your mob drops under the mobs section in the loot configuration:

mobs:
  ZOMBIE:
    enabled: true
    sound: "ENTITY_PLAYER_LEVELUP"
    pool:
      ancient_coin_advanced:
        weight: 5
        chance: 0.05
  ENDER_DRAGON:
    enabled: true
    sound: "UI_TOAST_CHALLENGE_COMPLETE"
    pool:
      dragon_heart_relic:
        weight: 1
        chance: 1.0

Understanding the Keys

Key	Description
`ENTITY_TYPE`	The exact Bukkit EntityType enum (e.g., `ZOMBIE`, `SKELETON`, `ENDER_DRAGON`).
`sound`	(Optional) A Bukkit Sound enum to play directly to the player who got the kill when the relic drops.
`weight`	The probability weight of this relic being selected from the pool.
`chance`	The final chance (0.0 to 1.0) of the relic dropping. For example, `0.05` means a 5% drop rate.

Relic Sets Configuration (relic_sets.yml)

Relic Sets allow you to link multiple individual relics into a unified set. When a player manages to collect and equip all the required relics within a set simultaneously, they are rewarded with bonus attributes and custom visual/audio effects.

💡 Generator Tool

We highly recommend using our visual Relic Set Creator. It allows you to drag, drop, and link your existing relics together to generate the relic_sets.yml file automatically!

Configuration File (relic_sets.yml)

This system operates within its own dedicated configuration file. Below is an example of a complete set configuration:

relic_sets:
  merchant_fortune_set:
    relics:
      - golden_ring_advanced
      - ancient_coin_advanced
      - silver_necklace
    extra-stats:
      attributes:
        luck: 15.0
        max_health: 4.0
        knockback_resistance: 1.0

set_config:
  on-enable-sound:
    - "UI_TOAST_CHALLENGE_COMPLETE"
    - "BLOCK_BEACON_ACTIVATE"
  on-disable-sound:
    - "BLOCK_BEACON_DEACTIVATE"
  particle:
    - "VILLAGER_HAPPY"
    - "END_ROD"

Understanding the Keys

Key	Description
`relics`	A list containing the exact IDs of the relics required to complete the set.
`extra-stats.attributes`	Bonus attributes granted only when the entire set is equipped. These stack additively with the individual relic stats.
`set_config`	The global configuration block. This dictates what happens cosmetically when any set is completed or broken.
`on-enable-sound`	A list of Bukkit Sound enums played to the player exactly when they equip the final missing piece of a set.
`on-disable-sound`	A list of sounds played when a complete set is broken (e.g., the player removes one of the pieces).
`particle`	Bukkit Particle enums spawned around the player the moment the set becomes fully active.

Example Snippets

Complete configuration examples combining attributes, mechanics, and triggers.

Example 1: Advanced Shadow Cloak

A mobility-focused artifact granting speed, strength, and extra jumps.

shadow_cloak_advanced:
  name: "&8Advanced Shadow Cloak"
  material: BLACK_BANNER
  lore:
    - "&7Hides in the darkness"
    - "&7with deadly efficiency."
    - ""
    - "&eSpecial Effect:"
    - "&7• +&a7.0 &7Speed"
    - "&7• +&a5.0 &7Strength"
    - "&7• +&a1.5 &7entity reach range"
    - "&7• +&a1 &7extra mid-air jump"
  slots:
    - CLOAK
  tier: UNCOMMON
  glow:
    enable: true
    color: "#696969"
  custom_model_data: 4310022
  attributes:
    speed: 7.0
    strength: 5.0
  special_effects:
    entity_range: 1.5
    double_jump: 1

Example 2: Mystic Orchestra

An epic item that acts dynamically through sound execution on combat events.

mystic_orchestra:
  name: "&d&lOrquestra Mística"
  material: NOTE_BLOCK
  lore:
    - "&7A musical artifact that plays"
    - "&7melodies on every action."
    - ""
    - "&6Bonuses:"
    - "&7• +&a8.0 &7Luck"
    - "&7• +&a5.0 &7Speed"
  slots:
    - RELICS
  tier: EPIC
  glow:
    enable: true
    color: "#E91E63"
  custom_model_data: 7001
  attributes:
    luck: 8.0
    speed: 5.0
  commands:
    command-feedback: false

    onEquip:
      - "playsound minecraft:ui.toast.challenge_complete player %player_name% %player_x% %player_y% %player_z% 1 1"
      - "title %player_name% subtitle {\"text\":\"Mystic Orchestra Activated\",\"color\":\"white\"}"
      - "particle minecraft:note %player_x% %player_y% %player_z% 2 2 2 1 50"
    onEquip-chance: 1.0

    onUnequip:
      - "playsound minecraft:entity.villager.no player %player_name% %player_x% %player_y% %player_z% 1 0.8"
      - "particle minecraft:smoke %player_x% %player_y% %player_z% 0.5 0.5 0.5 0.05 20"
    onUnequip-chance: 1.0

    onDamage:
      - "playsound minecraft:block.note_block.bass player %player_name% %player_x% %player_y% %player_z% 1 0.5"
    onDamage-chance: 0.30

    onInterval:
      - "playsound minecraft:block.note_block.flute player %player_name% %player_x% %player_y% %player_z% 0.3 1.5"
      - "particle minecraft:enchant %player_x% %player_y% %player_z% 0.5 1 0.5 0 5"
    onInterval-chance: 0.1
    interval-ticks: 60

NotEnoughRelics Documentation

Core Features

Basic Structure

Required Keys

Attributes & Stats

The attributes Block

Available Attributes

Special Effects & Mechanics

Permanent Potion Effects

Utility Special Effects

Available Mechanics

Commands & Triggers

Event Listeners

Configuration Example

Structure Loot Generation (loot.yml)

Configuration Example

Understanding the Keys

Mob Drops (loot.yml)

Configuration Example

Understanding the Keys

Relic Sets Configuration (relic_sets.yml)

Configuration File (relic_sets.yml)

Understanding the Keys

Example Snippets

Example 1: Advanced Shadow Cloak

Example 2: Mystic Orchestra

The `attributes` Block