Skip to content

Configuration

Jump to bottom
VampireAchao edited this page Oct 28, 2026 · 2 revisions

Configuration

Every tunable setting lives in plugins/mmSupernaturals/config.yml. This page lists keys, defaults and actual meaning, grouped by module.

Defaults come from the file written on the first 1.5.1 start, and the key set is 172 keys — identical to 1.5.0. The plugin writes defaults only when config.yml does not exist; an existing file is never extended or migrated, with one deliberate exception: the 1.5.1 ghoul-truce upgrade (§5).

1. Loading and reload semantics

Behaviour Detail
First start config.yml missing → write all defaults and save
Later starts Read the existing file only; missing keys fall back to built-in defaults
/sn reload config Re-runs loadValues; does not write missing default keys; restart to verify changes
/sn reload data Re-reads data.yml and replaces the in-memory player list
/sn save Writes data.yml + config.yml
Truce lists Rebuilt (assigned, not appended) on every load, so a reload cannot double them
Material lists Read from the file, then completed by tier in memory — the file is not rewritten

Material settings are validated at startup: if a key whose name contains material names an item that does not exist in this version, the console prints a WARNING explaining that the ability using it cannot work. Material names inside the weapon/armour lists are resolved with Material.matchMaterial and silently skipped if unknown; entity names inside truce lists get an explicit WARNING.

2. General settings

Key Default Meaning
Spanish false Switches some command and login messages to Spanish
DebugMode false Verbose logging (damage, spells, timer, altar decisions)
MultiWorld false When on, players without supernatural.world.enabled do not trigger supernatural rules
EnableChatColors true Colours player names by race
EnableLoginMessage true Broadcasts “ xxx has joined the server.” on join
EnableJoinCommand false When on, players must /sn join (see the caveat in FAQ)
Supernatural.Truce.BreakTime 120000 Milliseconds before a broken truce recovers
Supernatural.SpreadChance 0.35 Spread chance when a vampire/ghoul/werewolf kills a human (not enderborn)
Supernatural.Types 9 race names Types /sn convert accepts; removing one forbids converting to it

Material lists

Key Default contents
Material.Wooden STICK, BOW, and the wooden tier’s axe, hoe, pickaxe, shovel and sword (plus its spear, where the version has one) — the vampire’s wooden weakness
Material.Food 41 edible items (apple, bread, cooked fish, golden apple, cake, steak, carrot, honey bottle, …)
BurnableBlocks GRASS_BLOCK, OAK_LEAVES, AIR, WHEAT_SEEDS, OAK_LOG, BOOKSHELF (blocks a fire arrow can ignite)

How weapon and armour lists are read

Since 1.5.1 a list entry is a tier, not an item. The tier is the name before the first underscore, the kind is the name after the last one, and DIAMOND/NETHERITE are paired in both directions.

List Read as Effect
*.Weapon.Restrictions widened Naming any weapon adds its whole tier in all six kinds (sword, axe, pickaxe, shovel, hoe, spear), plus the paired tier
*.Armor tier-paired only A listed diamond piece also allows its netherite counterpart; no other kind is invented, because an allow-list that invents a kind hands out a slot nobody granted
Ghoul.Immunity tiers The list becomes a set of tier names; a hit is judged by tier + “is this a tool or weapon at all”

Two consequences worth knowing before you edit anything:

  1. You cannot ban a single tiered item any more. DIAMOND_SWORD in a restriction list means the diamond tier and the netherite tier, in all six kinds — twelve items. Things with no tier, such as BOW and STICK, stay single entries.
  2. The file is not rewritten for this. Widening happens in memory on load, so an old config.yml that names one diamond sword silently gains the eleven others the first time 1.5.1 loads it. Nothing to migrate, nothing to re-save.

The counts in the tables below are what this build writes by default, computed from the game: 42 weapons/tools (seven tiers × six kinds) and 28 armour pieces (seven tiers × four kinds).

3. Vampire

Power and combat

Key Default Meaning
Vampire.Power.Start 10000 Starting power on conversion
Vampire.Time.PowerGained 15 Per second (settled every 3 s, +45)
Vampire.Time.HealthGained 0.5 Per second; settled every 3 s, truncated to 1 HP
Vampire.Power.HealingCost 60 Power spent per regeneration tick
Vampire.Power.Kill.CreatureGain 100 Killing a creature
Vampire.Power.Kill.PlayerGain 500 Killing a player (victim must have > 500 power)
Vampire.Power.DeathPenalty 10000 Death penalty
Vampire.Kill.SpreadCurse true Whether killing a human may spread vampirism
Vampire.DamageFactor.AttackBonus 0.3 +30% attack at full power
Vampire.DamageFactor.DefenseBonus 0.8 20% melee reduction at full power
Vampire.DamageFactor.Wood 1.5 +150% from wooden melee weapons (BOW is listed but projectiles return early)

Sunlight and movement

Key Default Meaning
Vampire.Burn.InSunlight true Whether sunlight burns
Vampire.Burn.MessageEnabled true Whether to warn “vampires burn in sunlight”
Vampire.Burn.FireTicks 3 Extra fire ticks
Vampire.Burn.HelmetProtection GOLDEN_HELMET Helmet that prevents burning
Vampire.JumpDelta 1.2 Super-jump initial speed
Vampire.Power.JumpCost 1000 Super-jump cost
Vampire.Power.DrowningCost 90 Cost to cancel one drowning hit
Vampire.Power.TeleportCost 9000 Teleport cost
Vampire.Materials.Jump POPPY Jump trigger (left-click)
Vampire.TeleportMarker.Material POPPY Save-point trigger (right-click)
Vampire.Spell.Material BOOK Teleport trigger (left-click)
Vampire.GainHunger.Player 3 Hunger restored on a player kill
Vampire.GainHunger.Mob 2 Hunger restored on a mob kill

Altars and restrictions

Key Default Meaning
Vampire.Altar.Infect.Material GOLD_BLOCK Infect altar centre
Vampire.Altar.Infect.Surrounding.Material OBSIDIAN Surrounding block
Vampire.Altar.Infect.Surrounding.Radius 7 Counting-sphere radius
Vampire.Altar.Infect.Surrounding.Count 20 Minimum block count
Vampire.Altar.Infect.Recipe.Materials mushroom stew, bone, gunpowder, redstone Materials to pay
Vampire.Altar.Infect.Recipe.Quantities 1, 10, 10, 10 Positional match with the line above
Vampire.Altar.Cure.Material LAPIS_BLOCK Cure altar centre
Vampire.Altar.Cure.Surrounding.Material GLOWSTONE Surrounding block
Vampire.Altar.Cure.Surrounding.Radius 7 Counting radius
Vampire.Altar.Cure.Surrounding.Count 20 Minimum count
Vampire.Altar.Cure.Recipe.Materials water bucket, milk bucket, sugar, wheat Cure materials
Vampire.Altar.Cure.Recipe.Quantities 1, 1, 20, 20 Positional match
Vampire.Truce.Creatures 41 hostile mobs Truce list
Vampire.Weapon.Restrictions [none] Banned weapons; none resolves to null, i.e. no restriction
Vampire.Armor AIR, 28 tier pieces, TURTLE_HELMET (30 entries) Allowed armor

Recipes are positional. When Materials and Quantities differ in length, the reader throws once per out-of-range index and logs it. Add a material and its quantity together.

4. Priest

Location and altar

Key Default Meaning
Priest.Church.World world Legacy: world of the first church
Priest.Church.Location.X/Y/Z 0 / 80 / 0 Legacy: coordinates of the first church
Priest.Church.Locations maintained by the plugin Church list, formatted world,x,y,z
Priest.Banish.World world Banish point world
Priest.Banish.Location.X/Y/Z 0 / 80 / 0 Banish point coordinates
Priest.Church.AltarMaterial DIAMOND_BLOCK Altar block

The church radius is hard-coded at 10 blocks (PRIEST_CHURCH_RADIUS) and cannot be configured. /sn setChurch clears and then writes; use /sn church add for multiple churches. Priest.Church.Locations mirrors the first church into the four legacy keys.

Power and damage

Key Default Meaning
Priest.Power.StartingAmount 10000 Starting power
Priest.Power.DeathPenalty 2000 Death penalty
Priest.DamageFactor.AttackBonusSuper 1.0 +100% vs. supernatural at full power
Priest.DamageFactor.AttackBonusHuman 0 No bonus vs. the human side
Priest.DamageFactor.FireTicks 50 Ignition duration when hitting the supernatural (except demons)

Spell costs

Key Default Meaning
Priest.Power.Banish 4000 Banish
Priest.Power.Exorcise 9000 Exorcise
Priest.Power.Cure 1000 Purify (target must also hold flint)
Priest.Power.HealOther 1000 Heal
Priest.Spell.HealAmount 10 Heal amount (HP)
Priest.Power.Drain 1000 Drain
Priest.Spell.DrainFactor 0.15 Fraction of the target’s current power stolen
Priest.Power.GuardianAngel 5000 Guardian Angel
Priest.Spell.Material FEATHER, SUGAR, FLINT, PAPER, BOOK Fixed order: banish, exorcise, purify, heal, drain
Priest.Spell.Material.GuardianAngel WHITE_WOOL Guardian Angel trigger

The five entries in Priest.Spell.Material map to the five spells by position, not by name. Changing materials is fine; changing the order changes which spell is which.

Donations and restrictions

Key Default Meaning
Priest.Church.Recipe.Materials gold ingot, glowstone dust, redstone, bread Materials to become a priest
Priest.Church.Recipe.Quantities 4, 4, 8, 30 Positional match
Priest.Church.Donation.Materials apple, cod, cooked cod, cooked porkchop, bread Accepted donations
Priest.Church.Donation.Rewards 9000, 510, 500, 210, 80 Power per item, positionally matched
Priest.Armor [AIR] No armor may be worn
Priest.Weapon.Restrictions [none] No weapon restriction by default

5. Ghoul

Key Default Meaning
Ghoul.Power.Start 5000 Starting power
Ghoul.Power.Kill.CreatureGain 200 Killing a creature
Ghoul.Power.Kill.PlayerGain 1000 Killing a player (victim must have > 1000 power)
Ghoul.Power.DeathPenalty 2000 Death penalty
Ghoul.Kill.SpreadCurse true Whether killing a human may spread the curse
Ghoul.DamageFactor.AttackBonus 2 +200% attack at full power
Ghoul.DamageFactor.DefenseBonus 0.65 35% melee reduction at full power
Ghoul.WaterDamage 4 Water damage per second
Ghoul.Time.HealthGained 0.1 Per second; settled every 10 s as 1 HP
Ghoul.Summon.Material PORKCHOP Zombie summon trigger
Ghoul.Power.Summon 1000 Summon cost
Ghoul.RightClickSummon false true switches summoning to right-click
Ghoul.UnholyBond.Material BONE Bond trigger
Ghoul.Power.UnholyBond 50 Cost per damage transfer
Ghoul.Weapon.Restrictions 44 items (BOW, STICK + 42 tier weapons) Banned weapons
Ghoul.Truce.Creatures 19 grave mobs Truce list
Ghoul.Immunity 12 names — the diamond and netherite tiers in all six kinds Weapons the ghoul is immune to as a victim; read as tier names
Ghoul.Armor AIR, 28 tier pieces, TURTLE_HELMET Allowed armor

Ghoul.Immunity is the defensive list: someone hitting a ghoul with a diamond spear deals 0. It is separate from Weapon.Restrictions (what the ghoul itself may not use). Because the list is read as tiers, editing one entry affects a whole material.

The 19 grave mobs, in the order the file writes them:

zombie family   ZOMBIE, ZOMBIE_VILLAGER, HUSK, DROWNED, ZOMBIFIED_PIGLIN,
                GIANT, ZOGLIN, ZOMBIE_HORSE, ZOMBIE_NAUTILUS, CAMEL_HUSK
skeleton family SKELETON, STRAY, BOGGED, PARCHED, WITHER_SKELETON, SKELETON_HORSE
the rest        PHANTOM, CREEPER, ENDERMAN

1.5.1 upgrades exactly the old default. Six creatures were the default before; because a default is only written when the file is created, an existing server would keep them for ever. On startup, a list that still holds exactly the old six (ZOMBIE, ZOMBIE_VILLAGER, DROWNED, HUSK, ZOMBIFIED_PIGLIN, GIANT) is replaced with the nineteen and the file is saved; a list you have edited is left alone and logged. The check is idempotent — the widened list no longer equals the old one.

6. Werewolf

Key Default Meaning
Were.Power.Start 5000 Starting power
Were.Power.Kill.CreatureGain 20 Killing a creature
Were.Power.Kill.PlayerGain 100 Killing a player (victim must have > 100 power)
Were.Power.DeathPenalty 2000 Death penalty
Were.Kill.SpreadCurse true Whether a night kill of a human may spread lycanthropy
Were.Power.Food 100 Power per food item eaten
Were.DamageFactor.AttackBonus 5 +500% at full power (night only)
Were.DamageFactor.Fall 0.5 Fall damage multiplier
Were.Time.HealthGained 0.2 Per second; settled every 5 s as 1 HP (night only)
Were.DashDelta 4 Dash initial speed
Were.Power.Dash 400 Dash cost
Were.Material.Dash FEATHER Dash trigger
Were.Material.Summon PORKCHOP Wolf summon trigger
Were.Power.Summon 2000 Wolf summon cost
Were.WolfTruce true Peace with wolves
Were.Wolfbane.Trigger BOWL Wolfbane trigger
Were.Wolfbane.Materials 4 base flowers ×10 + every other flower ×1 + bowl Wolfbane recipe
Were.Wolfbane.Quantities positionally matched Quantity table
Were.Weapon.Restrictions 44 items (BOW, STICK + 42 tier weapons) Banned at night
Were.Armor AIR, 28 tier pieces, TURTLE_HELMET (30 entries) Allowed armor

If Were.Wolfbane.Quantities is shorter than Materials, missing entries default to 1 (no exception), but keeping them the same length is safer.

7. Demon

Key Default Meaning
Demon.Power.Start 10000 Starting power
Demon.Power.DeathPenalty 10000 Death penalty
Demon.Power.CreatureKill 20 Killing a creature
Demon.Power.PlayerKill 100 Killing a player (victim must have > 100 power)
Demon.Power.Gain 40 Power per lava tick
Demon.Power.Loss 4 Power lost per second; settled every 5 s as −20
Demon.Healing 1 Healing per lava tick
Demon.Power.Fireball 2000 Fireball cost
Demon.Fireball.Material REDSTONE Fireball trigger
Demon.Fireball.Damage 10 Fireball explosion damage
Demon.Power.Snare 1000 Cobweb cost
Demon.Snare.Duration 10000 Cobweb duration (ms)
Demon.Snare.Material INK_SAC Cobweb trigger
Demon.Power.Convert 2000 Cost to convert someone into a demon
Demon.SnowballAmount 30 Snowballs needed for the cure
Demon.DamageFactor.FireTicks 50 Ignition duration from the 35% chance when hitting a player
Demon.Armor [AIR] No armor may be worn
Demon.Weapon.Restrictions [none] No weapon restriction by default

The demon’s power leak has two exemptions: the world is the Nether, or the block underfoot is fire/lava. Only when neither holds does it drain.

8. WitchHunter

Key Default Meaning
WitchHunter.Power.StartingPower 10000 Starting power
WitchHunter.Power.DeathPenalty 500 Death penalty
WitchHunter.Power.PlayerKill 2000 Killing a player (victim must have > 2000 power)
WitchHunter.Power.CreatureKill 0 Killing a creature (nothing by default)
WitchHunter.Bounty.MaxNumber 5 Concurrent bounties
WitchHunter.Bounty.CompletionBonus 8000 Extra reward for completing a bounty
WitchHunter.Power.ArrowFire 100 Fire arrow cost
WitchHunter.Power.ArrowTriple 100 Triple arrow cost
WitchHunter.Power.ArrowPower 1000 Power arrow cost
WitchHunter.Power.ArrowGrapple 500 Grapple arrow cost
WitchHunter.ArrowPower.DamageFactor 2.0 Power arrow +200% (×3 total)
WitchHunter.PowerArrow.Cooldown 15000 Power arrow cooldown (ms)
WitchHunter.FallReduction 3 Fall damage reduction
WitchHunter.FireArrow.FireTicks 100 Fire arrow ignition duration
WitchHunter.ArrowTypes fire, triple, power, grapple, normal Left-click cycle order
WitchHunter.Hall.Message WitchHunter Text a hall sign must contain
WitchHunter.Armor AIR + four leather pieces Leather only
WitchHunter.Weapon.Restrictions 42 items (42 tier weapons, no bow) Banned weapons

WitchHunter.PowerArrow.Cooldown is the power arrow’s own recovery, and only that arrow’s. Until 1.5.1 it was checked before the arrow type was read, so a single power shot locked fire, triple, grapple and normal for the same fifteen seconds. A refused shot now says how many seconds are left.

9. EnderBorn

Key Default Meaning
EnderBorn.DamageFactor.AttackBonus 0.3 +30% at full power when the roll succeeds
EnderBorn.DamageFactor.DefenseBonus 0.5 Pearl guard: 50% reduction at full power
EnderBorn.Power.Protect 500 Cost per pearl guard
EnderBorn.Power.DeathPenalty 300 Death penalty
EnderBorn.Power.Kill 50 Power gained from a creature / stolen from a player
EnderBorn.Power.EnderPearl 100 Power from right-clicking a pearl
EnderBorn.Convert.Chance 0.1 New in 1.5.0: conversion chance on a player kill
EnderBorn.Weapon.Restrictions 18 items (copper, diamond, netherite × six kinds) Banned weapons

The attack-bonus chance is hard-coded at 35% (ATTACK_BONUS_CHANCE) and not configurable; the conversion chance is.

10. Angel

Key Default Meaning
Angel.Power.Heal.HealthGain 5 Healing per cast
Angel.Power.Heal.PowerCost 3000 Heal cost
Angel.Power.Cure.PowerCost 6000 Purify cost
Angel.Power.Summon.PowerCost 5000 Summon cost (also consumes 1 offering)
Angel.Power.Jump.PowerCost 1000 Jump cost
Angel.JumpDelta 1.2 Jump initial speed
Angel.Power.Kill.MonsterGain 30 Power from killing a monster
Angel.Power.Swim.PowerGain 50 Power per 10 s in water

The angel has no Power.Start: it begins at 0. It also has no armor/weapon config tables — both limits are hard-coded: AngelManager.forbiddenArmor refuses the golden, diamond and netherite tiers, and the only weapon limit is “no diamond- or netherite-tier weapon on animals”. Neither is configurable; changing them means changing code.

11. Altars and recipes at a glance

Ritual Centre block Surrounding blocks (radius 7, ≥20) Materials (quantity)
Become a vampire GOLD_BLOCK OBSIDIAN mushroom stew 1, bone 10, gunpowder 10, redstone 10
Vampire back to human LAPIS_BLOCK GLOWSTONE water bucket 1, milk bucket 1, sugar 20, wheat 20
Become a priest DIAMOND_BLOCK none gold ingot 4, glowstone dust 4, redstone 8, bread 30
Wolfbane potion empty-bowl trigger none dandelion/poppy/red mushroom/brown mushroom ×10 each, every other flower ×1, bowl 1

A priest altar must be within 10 blocks of a registered church; the other two altars have no location requirement.

12. Tuning examples

Stop vampires burning in daylight

Vampire:
  Burn:
    InSunlight: false

Lower the spread chance to 10%

Supernatural:
  SpreadChance: 0.1

The enderborn’s conversion chance is a separate key; change EnderBorn.Convert.Chance as well.

Make ghouls completely safe in water

Do not set Ghoul.WaterDamage: 0 — the code still sets health and prints the warning. The cleaner approach is to grant supernatural.player.preventwaterdamage, or hand it out per world through a permissions group.

Ban a material for one race

Add a tier to the race’s *.Weapon.Restrictions list, for example:

Demon:
  Weapon:
    Restrictions:
      - DIAMOND

DIAMOND is not a real item, but the tier reader takes the name before the first underscore, so listing it bans the whole diamond tier — and, because diamond and netherite are paired, the netherite tier too. Six kinds each: sword, axe, pickaxe, shovel, hoe, spear. Listing DIAMOND_SWORD instead produces the same twelve items; the kind is not a way to be more specific.

Single entries still work for things with no tier, such as BOW and STICK.

none is only a placeholder, not “ban everything”. And if you want to ban one sword without its tier, configuration cannot express it — that needs a code change in MaterialTiers.

Raise starting power

Change *.Power.Start, but the cap is always 10,000 (SuperNPlayer.MAX_POWER is hard-coded); 20000 is clamped to 10000. Going beyond the cap requires a code change.

Register multiple churches

/sn church add      # register the current position
/sn church list     # list them all
/sn church remove   # remove the nearest one (within 10 blocks)
/sn church clear    # remove all

13. Configuration checklist

After editing, check these in order:

  1. Is every material name valid for this version? Look for is not a material in this version in the startup log.
  2. Are Materials and Quantities the same length?
  3. Does Supernatural.Types still contain the race you want to convert to?
  4. Is the altar’s Surrounding.Count greater than 0? With 0 and no surrounding blocks, right-clicking the centre returns silently.
  5. Is a church registered? /sn church list should show something.
  6. Is the banish point set? Banish refuses to cast without one.
  7. Are you reading [none] as “all weapons banned”?
  8. Did you mean to ban one item? A tiered name bans its whole tier, its paired tier, and all six kinds — twelve items, not one.
  9. Did you name a mob this version does not have? Truce lists log a WARNING and skip it instead of crashing, so a missing truce fails quietly in the log rather than loudly at startup.

Overview

Reference

Practice

Clone this wiki locally