Skip to content

Configuration

Jump to bottom
okereke-dev edited this page Jul 17, 2026 · 8 revisions

Configuration

RPGMood ships four config files, generated automatically in plugins/RPGMood/ on first start: config.yml, subzones.yml, triggers.yml, and farming.yml. Edit them and run /rpgmood reload to apply changes.

  • subzones.yml — cave/structure subzone titles. See Zones → Subzones.
  • triggers.yml — time/weather/block-break events. See Ambient Events.
  • farming.yml — crops, seasons, recipes, and animals. See Farming.
  • config.yml — everything else, detailed below (mob scaling, zone clusters, Squaremap, villages, messages, death messages).

As of v1.10.0, there is no zones.yml. The curated biome/WorldGuard zone list it held was removed — zones are now entirely organic zone clusters, generated at runtime and persisted to dynamiczones.yml (not hand-edited). See Zones.

New keys auto-merge into your existing files. As of v1.7.0, config.yml, subzones.yml, and triggers.yml/farming.yml gain any config key added by a newer plugin version automatically on startup (and on /rpgmood reload) — nothing you've already customized is touched, only genuinely missing keys get filled in with their default value. One trade-off: the first time a file is merged, it loses its comments (Bukkit's YAML writer doesn't preserve them) — every value, yours and the new defaults, is kept exactly.

As of v1.8.0, a handful of the most commonly-tuned config.yml keys — spawn_protection.radius and mob_scaling.early_game_fraction/parity_level/night_bonus/thunder_bonus — can also be adjusted in-game without touching YAML at all, via the Admin Config panel in the GUI menu (rpgmood.admin). It writes straight back to config.yml on disk, same effect as hand-editing the file and reloading. (The panel briefly also had a weather_effects.enabled toggle; that config section was removed in v1.10.0, see below.)

settings

Key Type Default Description
zone_change_cooldown Integer (seconds) 45 Minimum time between zone-change feedback for the same player
particle_update_interval Integer (ticks) 40 Reserved for future ambient particle scheduling — not yet read by any feature

dynamic_zones

Governs the organic zone cluster system that replaced the old fixed 256×256 grid in v1.10.0 — see Zones for the full flood-fill/naming explanation.

Key Type Default Description
max_cluster_chunks Integer (chunks) 576 Max chunks a single flood-fill will claim into one cluster (576 ≈ 24×24 chunks, ~384×384 blocks)
creation_throttle_ms Integer (ms) 750 Minimum time between a single player's own cluster creations. Only gates creating a brand-new cluster for a never-before-seen chunk — looking up an already-known chunk is never throttled 
dynamic_zones:
  max_cluster_chunks: 576
  creation_throttle_ms: 750

square_map

Optional Squaremap integration — no effect if the squaremap plugin isn't installed. See Zones → Squaremap integration and Compatibility.

Key Type Default Description
layer_priority Integer 3 Squaremap layer ordering priority for the "RPGMood Zones" layer
zone_fill_opacity Decimal (0–1) 0.18 Fill opacity of each zone cluster's rectangle on the map 
square_map:
  layer_priority: 3
  zone_fill_opacity: 0.18

ambient_sounds

Low-probability day/night flavor sound near each player, checked on the same ~1s tick as everything else in AmbientTask — purely cosmetic, no chat/action-bar message, and independent of the time_events/weather_events in triggers.yml. See Ambient Events.

Key Type Default Description
enabled Boolean true Master switch
chance Decimal (0–1) 0.02 Chance per player per ~1s tick that a sound plays at all
day List<Sound> [entity.parrot.ambient] Sound pool picked from at random during vanilla day
night List<Sound> [ambient.cave] Sound pool picked from at random during vanilla night (13000–23000 ticks) 
ambient_sounds:
  enabled: true
  chance: 0.02
  day:
    - "entity.parrot.ambient"
  night:
    - "ambient.cave"

Add more entries to day/night (any Bukkit Sound name, or a resource-pack custom key) to widen the pool — one is picked at random each time the chance roll succeeds.

Removed in v1.10.0: the weather_effects section (fog/wind mechanical effects during storms) was removed from config.yml entirely, alongside the curated zones.yml system. See Ambient Events.

messages

Key Default
delivery ACTION_BAR — ambient messages (time/weather events, farming/animal feedback) go to the action bar instead of chat. Set to CHAT for the traditional behavior. This is the server-wide default; a player can override it for themselves with the Action Bar Delivery toggle in the GUI menu's Settings panel (writes player_actionbar.<uuid>). Doesn't affect zone entry — that's Title/Subtitle only, see Zones
no_permission &c[RPGMood] You do not have permission to use this command.
plugin_reloaded &a[RPGMood] Configuration reloaded successfully.
toggle_enabled &a[RPGMood] Effects enabled.
toggle_disabled &e[RPGMood] Effects disabled.
player_join &a→ {player} joined the world.
player_join_first_time &6✨ {player} arrived for the very first time!
player_quit &7← {player} left the world.
join_sound entity.player.levelup
join_first_time_sound ui.toast.challenge_complete
quit_sound entity.villager.no

player_join/player_join_first_time/player_quit replace the vanilla join/quit chat broadcast entirely (the vanilla message is suppressed). {player} is replaced with the player's name. Each is sent through broadcastAmbient, so every online player receives it via their own delivery preference (action bar or chat, per the delivery setting/toggle above), along with the matching sound played to every online player. First-time joins (!player.hasPlayedBefore()) use player_join_first_time + join_first_time_sound instead of the regular join template. Set any *_sound key blank to disable just the sound for that event.

Every message routed through delivery (all of AmbientTask's time/weather events, plus all farming/animal interaction feedback) is centralized in MessageService, and action-bar messages are sticky — resent twice, a second apart, so a short vanilla fade or a different message a moment later doesn't erase it before it's been read. If a newer message is sent to the same player before a resend fires, the stale resend is skipped instead of flashing old text back over the new one.

Achievement unlocks always go to chat regardless of delivery — see Achievements → Notifications.

spawn_protection

Key Type Default Description
enabled Boolean true Master switch
radius Decimal (blocks) 64 Hostile mobs never naturally spawn within this distance of world spawn 
spawn_protection:
  enabled: true
  radius: 64

Only blocks natural spawns of Monster entities (same gate mob_scaling.hostile-only uses) — passive mobs and plugin/command-summoned entities are unaffected. Keeps the immediate spawn area/starter base safe without meaningfully delaying the first real encounter with danger once you leave it.

mob_scaling

See Mob Scaling for the full formula. Quick reference:

Key Type Default Description
enabled Boolean true Master switch
hostile-only Boolean true Only scale Monster entities
max-level Integer 40 Upper clamp on the computed level
early_game_fraction Decimal 0.85 Health/damage/follow-range multiplier at level 1, relative to each mob's own vanilla stat (non-boss mobs)
parity_level Integer 8 Level at which the health/damage/follow-range multiplier reaches exactly 1.0 (vanilla-equivalent), non-boss mobs
armor_per_level Decimal 0.25 Armor added per level (non-boss mobs)
speed_per_level Decimal 0.0015 Movement speed added per level
boss_scaling.* — see below Separate hard curve for the 4 major bosses — see Mob Scaling → Boss hard curve
follow_range_cap Decimal (blocks) 36 Hard cap on FOLLOW_RANGE after level scaling — pathfinding safety net
knockback_resist.* — see below Progressive KNOCKBACK_RESISTANCE from level 25+
attack_speed.* — see below Light ATTACK_SPEED bonus from level 20+
smart_aggro.* — see below Forced-aggro AI for mid/high-level mobs — see Mob Scaling → Smart aggro
archery.* — see below Bow/crossbow aim quality by level — see Mob Scaling → Dynamic archery
advanced_ai.* — see below Pack assist / archer kite / creeper fuse — see Mob Scaling → Advanced AI
seasonal.* — see below Seasonal combat modifiers — see Mob Scaling → Seasonal combat
elite_glow.* — see below Combat-gated colored glow for elites/bosses — see Mob Scaling → Elite glow
elite_equipment.* — see below Offhand shield/totem/torch loadouts — see Mob Scaling → Elite equipment
corrupt_sounds.enabled Boolean true Warden-hurt-sound flavor for L20+ zombies/skeletons taking damage in deep biomes
environment.* — see below Fire immunity + spider dodge for high-level mobs — see Mob Scaling → Elite environment effects
night_bonus Integer 2 Extra flat level added while it's vanilla night (13000–23000 ticks) where the level is computed
thunder_bonus Integer 2 Extra flat level added while that world is currently thundering. Stacks with night_bonus
radius.step_distance Decimal (blocks) 180 Distance per "ring" of difficulty from spawn
players_bonus_per_player Integer 1 Level added per nearby player (within ~30 blocks)
name_format String "&cLv. {level} {name}" Custom name shown above scaled mobs. Supports {level} and {name}
show_name_tags Boolean false Show the floating name tag above scaled mobs. Off by default — RPGMood shows level via particle auras instead
particle_aura Boolean true Level-tiered coloured particles around scaled mobs (blue → yellow → orange → red as level rises), only rendered for mobs within ~30 blocks of a player
bonus_xp_per_level Integer 2 Bonus XP granted per level when a player kills a scaled mob. 0 disables
base-levels Map<EntityType, Integer> see below Per-mob-type difficulty seed. As of v1.18.0 also seeds the 4 bosses (ELDER_GUARDIAN: 14, WITHER: 18, WARDEN: 20, ENDER_DRAGON: 22) well above parity_level so they only ever get buffed
biome-bonuses Map<Biome, Integer> see below Flat bonus per biome
structure-bonuses Map<structure key, Integer> see below Flat bonus near a vanilla structure
announcement.* — see below Server-wide broadcast when a high-level mob spawns
affixes.* — see below RPG modifiers (Swift, Wraith, Bleeding, etc.) scaled mobs can roll — see Mob Scaling → Affixes 
mob_scaling:
  boss_scaling:
    enabled: true
    growth_per_level_above_base: 0.12
    max_multiplier: 4.0
    armor_per_level: 0.75
  follow_range_cap: 36
  knockback_resist:
    min-level: 25
    per-level: 0.02
    max: 0.85
  attack_speed:
    min-level: 20
    per-level: 0.02
    max-bonus: 0.4
  smart_aggro:
    enabled: true
    los-min-level: 15
    los-radius: 28
    omniscient-min-level: 30
    omniscient-radius: 36
    max-retargets-per-tick: 40
    cooldown-ticks: 40
  archery:
    enabled: true
    clumsy-max-level: 7
    clumsy-spread: 0.35
    laser-min-level: 15
    predictive-min-level: 30
    arrow-speed: 1.6
    tracer-particles: true
  advanced_ai:
    enabled: true
    pack:
      min-level: 20
      radius: 20
      max-allies: 5
      chunk-cooldown-seconds: 3
    kite:
      min-level: 30
      keep-distance: 8
    creeper:
      min-level: 25
      base-fuse-ticks: 30
      min-fuse-ticks: 12
      advance-while-ignited: true
  seasonal:
    enabled: true
    winter:
      armor-bonus: 2.0
      arrow-slowness-ticks: 40
      arrow-slowness-amplifier: 0
    autumn:
      swift-chance-bonus: 0.20
    summer:
      burn-chance: 0.35
      burn-ticks: 60
  elite_glow:
    enabled: true
    min-level: 35
    combat-only: true
    max-active: 64
    combat-timeout-seconds: 10
  elite_equipment:
    enabled: true
    shield-chance: 0.25
    shield-min-level: 20
    shield-damage-reduce: 0.30
    totem-chance: 0.08
    totem-min-level: 30
    torch-chance: 0.40
    torch-min-level: 15
  corrupt_sounds:
    enabled: true
  environment:
    enabled: true
    fire-immune-min-level: 25
    spider-dodge-min-level: 25
    spider-dodge-chance-per-level: 0.02
    spider-dodge-max-chance: 0.35
  base-levels:
    ZOMBIE: 1
    SKELETON: 2
    SPIDER: 2
    CREEPER: 3
    ENDERMAN: 4
    WITHER_SKELETON: 5
    ELDER_GUARDIAN: 14
    WITHER: 18
    WARDEN: 20
    ENDER_DRAGON: 22
  biome-bonuses:
    PLAINS: 0
    FOREST: 1
    MOUNTAINS: 3
    DEEP_DARK: 5
    SOUL_SAND_VALLEY: 4
  structure-bonuses:
    stronghold: 3
    desert_pyramid: 2
    jungle_temple: 2
    woodland_mansion: 4
    ocean_monument: 4
    fortress: 3
    ancient_city: 5
  announcement:
    enabled: true
    min-level: 25
    cooldown-seconds: 120
    message: "&c⚠ A Level {level} {name} has emerged in {biome}!"

Any EntityType / Biome not listed defaults to 0 (or 1 for base-levels) — you don't need to list every enum value, only the ones you want to deviate from baseline. See Mob Scaling for the rewards, announcement, combat AI, and boss-curve behavior in detail.

Fixed in v1.9.0: structure-bonuses used the dead keys jungle_pyramid/nether_fortress, which never matched anything in Minecraft's real StructureType registry (jungle_temple/fortress) — mobs near those two structures silently never got their configured bonus. Renamed to the correct keys above; ancient_city was added later as a new key.

villagers

Seasonal villager trades, a Deep Dark wandering-trader offer, per-village reputation, and light cartographer crop/emerald quests — emeralds and crops only, no custom currency. See Villages for the full behavior.

Key Type Default Description
enabled Boolean true Master switch for the whole village trading/reputation/quest system
seasonal_trades.enabled Boolean true Inject seasonal buy/sell offers into Farmer and Cleric trade menus
seasonal_trades.buy_price_emeralds Integer 2 Emeralds a Cleric charges per seasonal crop bought
seasonal_trades.sell_crop_count Integer 8 Crops a Farmer buys per trade use
seasonal_trades.sell_reward_emeralds Integer 1 Emeralds a Farmer pays per trade use
seasonal_trades.max_uses Integer 12 Max uses before a seasonal trade slot is exhausted (resets when trades are re-injected)
seasonal_trades.spring/summer/autumn/winter List<Material> see config.yml Crop materials in season for that quarter (e.g. spring: CARROT, POTATO, SWEET_BERRIES)
wandering_deep_dark.enabled Boolean true Offer Echo Shard / Sculk Sensor trades from a wandering trader in (or near a player in) the Deep Dark
wandering_deep_dark.max_uses Integer 4 Max uses per Deep Dark trade slot
wandering_deep_dark.echo_price Integer 12 Emeralds per Echo Shard
wandering_deep_dark.sensor_price Integer 8 Emeralds per Sculk Sensor
rep.per_trade Integer 1 Reputation gained per completed trade with a villager (not a wandering trader) in a detected village
rep.show_overlay Boolean true Show a chat message with the rep gained/total after each trade
quests.enabled Boolean true Offer a cartographer crop-delivery or emerald-spend quest when trading with a Cartographer near a village
quests.deliver_count Integer 16 Crops required for a DELIVER_CROP quest
quests.emerald_spend Integer 8 Emeralds required for a SPEND_EMERALDS quest
quests.rep_reward Integer 5 Reputation awarded on quest completion 
villagers:
  enabled: true
  seasonal_trades:
    enabled: true
    buy_price_emeralds: 2
    sell_crop_count: 8
    sell_reward_emeralds: 1
    max_uses: 12
    spring: [CARROT, POTATO, SWEET_BERRIES]
    summer: [MELON_SLICE, WHEAT, APPLE]
    autumn: [PUMPKIN, SWEET_BERRIES, APPLE]
    winter: [BROWN_MUSHROOM, RED_MUSHROOM, SWEET_BERRIES]
  wandering_deep_dark:
    enabled: true
    max_uses: 4
    echo_price: 12
    sensor_price: 8
  rep:
    per_trade: 1
    show_overlay: true
  quests:
    enabled: true
    deliver_count: 16
    emerald_spend: 8
    rep_reward: 5

death_messages

Fully documented on the Death Messages page. Top-level keys: fallback, causes (includes killers.player for PvP), biomes, killers, killer_synonyms, armed, modifiers, location_name_templates, location_name_descriptors (ships per-biome pools for common biomes plus default), location_names.

player_effects / player_titles / player_scoreboard

Not hand-edited — RPGMood writes player_effects.<uuid>: true|false, player_titles.<uuid>: true|false, and (as of v1.8.0) player_scoreboard.<uuid>: true|false here automatically when a player runs /rpgmood toggle, /rpgmood toggle titles, or /rpgmood toggle scoreboard respectively. See Zones → Sidebar scoreboard.

Persisted data files

None of these are hand-edited — each is written automatically by its owning feature and read back on startup / /rpgmood reload.

File Backs
stats.yml /rpgmood leaderboard — per-player deaths, zone changes, highest mob level killed. See Commands
achievements.yml /rpgmood achievements — unlock timestamps and progress counters. See Achievements
season.yml Current season and day-in-season. See Farming → Seasons
recipes.yml Per-player discovered recipes. See Farming → Cooking & recipes
animals.yml Owned animals and their affection/health/hunger/sickness state. See Farming → Animal husbandry
playerdata/<uuid>.yml /diary entries. See Commands
zonediscovery.yml /rpgmood zones — per-player discovered zones (display name, first-seen date, favorite flag). See Zones → Zone discovery
dynamiczones.yml Every zone cluster ever created — id, world, biome group, display name, center point, and member chunks. Permanent; a cluster is never removed or re-generated once written. See Zones
villagerep.yml Per-player, per-village reputation and any active cartographer quest. See Villages
playerlevel.yml /rpgmood level — per-player progression XP/level. See Commands → /rpgmood level

Clone this wiki locally