Skip to content

Configuration

Jump to bottom
okereke-dev edited this page Jul 3, 2026 · 4 revisions

Configuration

The config file is generated automatically at plugins/RPGLoot/config.yml on the first server start. Edit it and restart the server (or /reload confirm) to apply changes.

Full config.yml

# Master switch for combat stats and set bonuses.
# When false, RPGLoot items keep their rarity name, color, and lore tag but
# grant NO attribute bonuses, bonus stats, or set bonuses — pure cosmetic
# rarity system layered on top of unmodified vanilla combat.
stats-enabled: true

# Chance that a hostile mob drops a rarity item on death (0.0 - 1.0)
drop-chance: 0.08

# How bonus stats are displayed in item lore
# Options: percentage | absolute | mixed
stat-display: percentage

# Show floating damage numbers in combat (true/false)
damage-numbers: true

# Drop chance per rarity (%) — auto-normalized if they don't sum to 100
rarity-weights:
  common: 50
  uncommon: 30
  rare: 13
  hero: 5
  legendary: 2

# Items injected into vanilla structure chests on first generation
structure-loot:
  enabled: true
  # Probability that a recognized structure chest receives an RPGLoot item (0.0 - 1.0)
  inject-chance: 0.25

# Boss drops — guaranteed RPGLoot weapon on death
# min-rarity and max-rarity define the rarity range (inclusive)
boss-drops:
  enabled: true
  warden:
    chance: 1.0
    min-rarity: RARE
    max-rarity: LEGENDARY
  wither:
    chance: 1.0
    min-rarity: RARE
    max-rarity: LEGENDARY
  elder-guardian:
    chance: 0.8
    min-rarity: RARE
    max-rarity: HERO
  ender-dragon:
    chance: 1.0
    min-rarity: RARE
    max-rarity: LEGENDARY

# ══════════════════════════════════════════════════════════════════════
# ADVANCED BALANCE TUNING — see the "Advanced balance tuning" section below
# ══════════════════════════════════════════════════════════════════════
rarity-multipliers:
  COMMON:    { damage: [1.05, 1.05], speed: [1.00, 1.00] }
  UNCOMMON:  { damage: [1.05, 1.10], speed: [1.00, 1.05] }
  RARE:      { damage: [1.10, 1.20], speed: [1.00, 1.10] }
  HERO:      { damage: [1.20, 1.30], speed: [1.05, 1.15] }
  LEGENDARY: { damage: [1.30, 1.40], speed: [1.10, 1.20] }

bonus-stat-ranges:
  LIFESTEAL: { uncommon: [1,3], rare: [3,6], hero: [6,10], legendary: [8,12] }
  # ...one entry per BonusStat — see full list in the shipped config.yml

Options reference

stats-enabled

Type Default
Boolean true

Master switch for RPGLoot's mechanical effects. This is the key setting for servers that want a vanilla-first experience:

  • true (default) — Items get combat stat bonuses, bonus stats, and set bonuses as documented across the wiki.
  • false — Items keep their generated name, rarity color, and rarity tag in the lore, but no attribute modifiers, no bonus stats, and no set bonuses are applied. RPGLoot becomes a pure cosmetic/loot-flavor layer — a "Shadowfang Blade [Legendary]" behaves exactly like a vanilla Diamond Sword in combat.

Use this if you want RPGLoot's flavor (names, rarity colors, boss/structure loot variety) without touching PvP or PvE balance at all.

Changing this setting only affects newly generated items — items already in player inventories keep whatever stats they were generated with. Existing items are unaffected by a live toggle.

drop-chance

Type Default Range
Decimal 0.08 0.0 – 1.0

The probability that a hostile mob drops a rarity item when killed by a player.

  • 0.0 — never drops
  • 0.08 — 8% chance per kill (default)
  • 1.0 — always drops

stat-display

Type Default Options
String percentage percentage · absolute · mixed

Controls how attack damage, speed, and defense bonuses are shown in the item lore.

Option Example output
percentage Attack Damage: +20%
absolute Attack Damage: +1.40
mixed Attack Damage: +1.40 (+20%)

Bows and crossbows always show Projectile weapon since they have no ATTACK_DAMAGE attribute.

damage-numbers

Type Default
Boolean true

Toggles floating damage numbers in combat. When enabled, a number appears above the target on every hit, color-coded by type (normal, crit, bleed, heal, smash).

rarity-weights

Type Default total
Integer map Recommended to sum to 100

Sets the relative drop chance of each rarity tier when a drop occurs. If the values don't sum to 100, the plugin auto-normalizes them and logs a warning:

[RPGLoot] WARNING: rarity-weights sum to 95 instead of 100 — weights have been normalized automatically.

structure-loot

Controls injection of RPGLoot items into vanilla structure chests.

Key Type Default Description
enabled Boolean true Enable/disable structure loot entirely
inject-chance Decimal 0.25 Probability a recognized chest receives an item

Set inject-chance: 0.0 to disable injection while keeping the feature enabled for future use.

Structure loot never contains Netherite. Max rarity per structure type is fixed (see Drop System).

boss-drops

Controls the guaranteed boss drop behavior.

Key Type Default Description
enabled Boolean true Enable/disable all boss drops
<boss>.chance Decimal varies Probability the boss triggers a drop on death
<boss>.min-rarity String RARE Minimum rarity for the rolled drop
<boss>.max-rarity String varies Maximum rarity for the rolled drop

Valid boss keys: warden · wither · elder-guardian · ender-dragon

Valid rarity values: COMMON · UNCOMMON · RARE · HERO · LEGENDARY

If an invalid rarity string is supplied, a warning is logged and the default value is used.

Example — make Warden always drop Legendary:

boss-drops:
  warden:
    chance: 1.0
    min-rarity: LEGENDARY
    max-rarity: LEGENDARY

Advanced balance tuning

Two additional sections at the bottom of config.yml let you tune exactly how powerful RPGLoot items are, without recompiling the plugin. The shipped defaults are the tested, vanilla-friendly values — only edit these if you want a different power level.

rarity-multipliers

Controls the damage/speed multiplier rolled for each rarity tier, applied over the item's vanilla base stat.

rarity-multipliers:
  COMMON:    { damage: [1.05, 1.05], speed: [1.00, 1.00] }
  UNCOMMON:  { damage: [1.05, 1.10], speed: [1.00, 1.05] }
  RARE:      { damage: [1.10, 1.20], speed: [1.00, 1.10] }
  HERO:      { damage: [1.20, 1.30], speed: [1.05, 1.15] }
  LEGENDARY: { damage: [1.30, 1.40], speed: [1.10, 1.20] }

Each value is [min, max] — a random multiplier is rolled in that range when the item is generated. Example: LEGENDARY damage: [1.30, 1.40] means a Legendary weapon deals between 30% and 40% more damage than the vanilla base.

Want a more subtle experience? Lower the max values, e.g. LEGENDARY: { damage: [1.10, 1.15], speed: [1.00, 1.05] } for a barely-noticeable power bump.

Want a more powerful experience? Raise them — but be mindful this is exactly the kind of change that can break PvP balance on populated servers.

bonus-stat-ranges

Controls the value range rolled for every bonus stat, per rarity tier (uncommon / rare / hero / legendary — Common items never roll a bonus stat). Full list of ~24 stats ships pre-populated with the default values documented on the Bonus Stats page.

bonus-stat-ranges:
  CRIT_CHANCE: { uncommon: [2,5], rare: [5,10], hero: [10,15], legendary: [15,20] }
  BLEEDING:    { uncommon: [20,30], rare: [30,45], hero: [45,60], legendary: [60,75] }
  # ...

Some stats have hard caps applied at runtime regardless of what you configure here, to prevent stacking exploits across multiple items/set bonuses: Dodge Chance (50%), Damage Reduction (60%), Fall Reduction (80%), Crit Chance (35%), Bleeding (60%). See Bonus Stats for details. Raising ranges above these caps has no additional effect.

If a stat or rarity key is missing or malformed, the plugin logs a warning and falls back to the compiled-in default for that entry only — a typo won't break the whole config.

Clone this wiki locally