FAQ

FAQ and Caveats

This page is organized by the symptom people actually report. Each answer tries to give the code-level cause instead of “try restarting”.

---

Installation and compatibility

Which servers are supported?

Paper 26.3. plugin.yml declares api-version: 26.3; older servers refuse to load it. Building requires JDK 25.

Are WorldGuard or a permissions plugin required?

Neither is required.

• WorldGuard is a softdepend: when present, the plugin reads the region’s PVP / MOB_SPAWNING flags; when absent, both are treated as allowed.
• Without a permissions plugin, Bukkit’s SuperPerms still applies the default values declared in plugin.yml.

Why does an OP never see any power cost?

Because supernatural.admin.infinitepower defaults to op, and its effect is: every negative power change is silently refused.

While testing as an OP:

• a demon outside lava does not lose power;
• spells do not cost power;
• Not enough power never appears;
• death does not cost power.

Since 1.5.0, the first time it applies the player gets a private message:

Your power never goes down: you hold supernatural.admin.infinitepower, which is given to operators by default.

To test the real economy, remove the node with your permissions plugin (for example lp user <name> permission unset supernatural.admin.infinitepower) or use a non-OP account.

Why did my config.yml change not take effect?

First confirm you edited plugins/mmSupernaturals/config.yml, not the defaults in the source. Then:

• /sn reload config re-runs loading but does not write missing keys.
• Restarting the server is the reliable check.

Why do new keys not appear in the file after upgrading?

The plugin writes defaults only when config.yml does not exist. An existing file is never extended or migrated.

New keys are read from their built-in defaults (for example EnderBorn.Convert.Chance defaults to 0.1). To make them appear, delete config.yml, let it regenerate, then reapply your values.

---

Turning

Right-clicking the altar does nothing at all?

Check in this order:

1. Zero surrounding blocks: useAltarInfect returns immediately when count == 0, with no message. Confirm there is obsidian/glowstone within radius 7.
2. Not enough blocks: prints “doesn't seem to be enough …”.
3. Missing permission: prints “You cannot use vampire altars.”.
4. Already supernatural: prints “This is of no use to you…”.
5. Priest altar: it must be within 10 blocks of a registered church; otherwise isChurch() returns false and it returns silently.

I killed 3 supernatural types but got no witch hunter invitation?

All three conditions are required:

• The killer must be human (isHuman()).
• The 3 superTypes must be distinct.
• You must not die in between — a human death clears the recorded types.

When they are met, the invitation is scheduled 200 ticks (10 seconds) later.

Why can’t an angel turn back into a human?

This is a consequence of the current rules, not an operation mistake:

• isSuper() returns false for an angel.
• The priest’s Exorcise/Purify and the angel’s Purify all require a supernatural target.
• So there is no in-game way to purify an angel.

Only an admin’s /sn cure <player> can do it.

Why does the enderborn’s “5 deaths” counter reset on relog?

EnderBornManager.deathTimesMap is an in-memory HashMap; it is never written to data.yml or storage.dat. Relogging or restarting clears it.

Why do a new angel/enderborn start with 0 power?

Their conversion paths call convert without a starting power; the other races explicitly pass 5,000 or 10,000. They have to earn it (an angel swims, an enderborn trades pearls for power).

---

Abilities

Why does a werewolf have almost no abilities by day?

By design: the attack bonus, wolf summoning, dash and regeneration all check worldTimeIsNight. The plugin’s definition of night is world time > 12,400. Using those items by day prints Cannot use this ability during the day. and costs nothing.

Why did my hit deal no damage / zero damage?

Check three things:

1. Is the weapon banned for your race? damagerEvent sets the damage to zero and prints “xxx cannot use this weapon!”. Defaults:
   • ghoul 44 items, witch hunter 42, enderborn 18;
   • werewolf only at night;
   • vampire/priest/demon default to [none], i.e. no restriction.
2. Is the target immune? A ghoul takes 0 from any diamond- or netherite-tier tool or weapon — the sword, but also the axe, pickaxe, shovel, hoe and spear.
3. Is this a non-PvP area? When WorldGuard’s PVP flag is deny, some spells and special arrows are refused.

Why won’t special arrows work?

• No arrows in the inventory: since 1.5.0 this prints You have no arrows to shoot..
• Outside a PvP area: prints You cannot use special arrows in non-PvP areas..
• Not enough power: prints a message and switches back to normal arrows.
• Power arrow still cooling down: prints You are still recovering from Power Shot (Ns). Switch arrow type to shoot something else. — note the second sentence. Since 1.5.1 only the power arrow is blocked by that cooldown; fire, triple, grapple and normal fire normally. Before that, one power shot locked all five.

Why did my grapple arrow cost 500 power and move me nowhere?

That was the bug 1.5.1 fixed. The pull used to set the player’s velocity, and a player’s position is the client’s to report, so the server’s speed was overwritten before it could mean anything. It also ran its whole chain inside one tick, so when it did move anybody it arrived as a teleport.

Now it is a teleport of one block per tick, stopping 3 blocks short, with fall distance held at zero until you land. And it will not keep power for a ride it did not give — this is refunded:

Why nothing happened	What you see
The arrow never left the block it was fired into	Nothing to pull you to (the arrow never left the block it was fired into) - 500 power returned.
What it caught is under 3 blocks away	Nothing to pull you to (it caught something only 2 blocks away) - 500 power returned.
The pull ran out of time	…(it ran out of time)…
The move was refused by a region plugin or the world border	…(the move was refused)…
Player and target in different worlds	…(what it caught is in another world)…
A later shot took the pull over	…(a later shot took over the pull)…

If you hold supernatural.admin.infinitepower, nothing was charged, so nothing is returned — the refund is the amount actually taken, not the setting.

Why does an ability refuse when my power is exactly its cost?

It should not, since 1.5.1. Every affordability check now goes through SuperNManager.canPay, which asks power >= cost; before that, each ability asked power > cost, so a bar of exactly 5,000 could not pay a 5,000-power ability — the one number it could not buy was its own. PowerCostTest pins the boundary now: 5,000 pays 5,000, 4,999.99 does not.

If you still see something refused at an exact amount, check what is being compared. The only strict comparisons left are reward gates, not costs: a kill pays out only when the victim held more than N power — 500 for a vampire, 1,000 for a ghoul, 2,000 for a witch hunter, 100 for a werewolf or demon. A victim sitting exactly on the threshold pays nothing, which is a payout rule and not a price.

Why does Banish do nothing?

• The target is not supernatural (priest, witch hunter and angel do not count).
• You are not in a PvP area.
• No banish point is set: since 1.5.0 it refuses to cast, costs nothing, and tells the admin to run /sn setBanish.
• Less than 4,000 power.

Why didn’t Guardian Angel trigger?

• It only works on a non-supernatural target.
• A priest can guard only one person at a time; guarding another removes the old one.
• It only triggers on a lethal hit; the check is health - damage <= 0 after damage calculation.
• On trigger the target returns to 20 HP and the guard is consumed.

Why did I die the moment I touched the church altar?

A non-priest supernatural who right-clicks the diamond-block altar is killed by holy light. It is an explicit branch in the implementation:

The holy power of the Church tears you asunder!

A ghoul has a 25% chance to be cleansed; every other race simply dies. The church is not a safe zone.

---

Power

Why doesn’t my power go up?

Each race has its own sources:

Race	Source
Vampire	+45 every 3 seconds (passive)
Werewolf	+100 per food item (bread excluded)
Ghoul	Kills
Demon	+40 per lava tick
Priest	Church donations
WitchHunter	Player kills and completed bounties
EnderBorn	+100 per pearl right-click, plus kills
Angel	+50 per 10 seconds in water, plus monster kills

If none of these apply, power is not supposed to go up.

Why does my power keep dropping?

• Demon outside the Nether and not standing in fire/lava: −20 every 5 seconds.
• Vampire regeneration: −60 every 3 seconds.
• Ghoul maintaining an Unholy Bond: −50 per transferred hit.
• EnderBorn pearl guard: −500 per hit.
• Death: each race has a fixed penalty (vampire and demon lose 10,000).

Can the power cap be changed?

Not through configuration. SuperNPlayer.MAX_POWER = 10000 is a hard-coded constant; setPower clamps anything to 0–10000. Setting *.Power.Start to 20000 still yields 10000.

Why didn’t /sn power <player> -5000 subtract anything?

Because when the target holds supernatural.admin.infinitepower, alterPower returns immediately for every negative delta. Remove the permission first.

Why was the power in my hand-edited save changed?

Since 1.5.0, SNPlayerHandler.load writes the loaded power back through the setter once, clamping it to 0–10000 and logging:

Power for <name> was <x> in the save file, which is not a power between 0.0 and 10000.0; it is <y> now.

NaN becomes 0: otherwise it compares false against every number, making every cost permanently free with no way back.

---

Configuration

Does [none] mean “ban every weapon”?

No. none is not a valid material and resolves to null; the list contains null, so contains(item.getType()) is always false — there is effectively no restriction.

Vampire, priest and demon all default to [none]. Only ghoul, witch hunter, enderborn (and the werewolf at night) have real weapon-ban lists.

Why did adding one diamond sword ban every netherite axe too?

Because a weapon list is read as materials, not as items (since 1.5.1). The reader splits a material name into a tier (before the first underscore) and a kind (after the last one), then expands:

• any tiered entry → that tier in all six kinds (sword, axe, pickaxe, shovel, hoe, spear);
• DIAMOND ↔ NETHERITE are paired, in both directions.

So DIAMOND_SWORD means twelve items: six kinds of diamond and six of netherite. DIAMOND means the same twelve. Entries with no tier, such as BOW and STICK, stay single. Armour lists work the other way round — they only pair the tier and never invent a kind, because an allow-list that invents a kind hands out a slot nobody granted.

Nothing in the file changes when this happens: widening is done in memory on load, so an old config.yml is quietly corrected rather than migrated.

My Ghoul.Truce.Creatures changed itself after upgrading to 1.5.1?

Once, on purpose. The default grew from 6 creatures to 19, and a default is only written when config.yml is created — so an existing server would never see it. On startup the plugin checks whether your list still holds exactly the old six (ZOMBIE, ZOMBIE_VILLAGER, DROWNED, HUSK, ZOMBIFIED_PIGLIN, GIANT); if it does, it writes the nineteen and logs:

Ghoul.Truce.Creatures was still the old six-mob default; it now names 19 grave mobs. Edit config.yml to taste.

If you had edited the list, it is left alone and the log says Ghoul.Truce.Creatures is a list of its own (N entries) - leaving it as it is. The upgrade cannot run twice, because the widened list no longer equals the old one.

An ability stopped working after I changed a material name?

Bukkit materials are an enum, and names change between versions. At startup the plugin scans every key containing material:

<key> is set to "<name>", which is not a material in this version - the ability that uses it cannot be used.

Seeing that line means the name does not exist in this version. Use a valid name, or delete config.yml and let it regenerate.

Must Materials and Quantities be the same length?

They are matched positionally.

• The vampire/priest recipes throw IndexOutOfBoundsException and log it when the quantity list is too short, then fall back to 1;
• Wolfbane tolerates a short list (missing entries become 1);
• The priest donation Rewards list also throws when too short.

Change both tables together.

How do I configure multiple churches? Why did /sn setChurch delete the others?

/sn setChurch means “there is one church, and it is here”: it calls clearChurches() and then addChurch().

For several:

/sn church add      # run once at each church location
/sn church list

The church radius is hard-coded at 10 blocks and cannot be configured.

Why didn’t changing Supernatural.SpreadChance affect the enderborn?

The enderborn uses a separate key, EnderBorn.Convert.Chance (default 0.1). SpreadChance only affects vampire, ghoul and werewolf.

Why does Spanish: true only translate part of the plugin?

It covers some command messages and the login broadcast; it is not a full localization.

---

Data and backups

Where is player data stored?

File	Contents
plugins/mmSupernaturals/data.yml	Race, old race, power, truce state
plugins/mmSupernaturals/storage.dat	Vampire teleport points, guardian angels, hunter applications
plugins/mmSupernaturals/config.yml	All configuration
plugins/mmSupernaturals/whitelistYaml.yml	Sign-up list

Backing up the whole plugins/mmSupernaturals/ directory is enough.

Why did power roll back after a crash?

Power changes are not written immediately. data.yml is written only:

• on a conversion / cure / revert;
• when the truce countdown changes;
• on /sn save;
• on a normal shutdown.

storage.dat is written only on a normal shutdown. An abnormal crash can lose recent teleport points, guardian angels and power changes.

Can I edit data.yml by hand?

Yes. It is ordinary YAML with !player tags. A minimal working entry:

- !player {name: Steve, playername: Steve, superType: vampire, power: 10000.0, superPower: 10000.0}

The same concept can appear under both a field name and a property name (playername/name, superType/type, superPower/power); if they disagree, the last one written wins, and 1.5.0 clamps the result on load.

Notes:

• Stop the server first, or the in-memory copy will overwrite your edit.
• superPower is clamped to 0–10000.
• superType must be one of Supernatural.Types.
• Do not break the !player tag or the indentation.

Can I edit storage.dat by hand?

No, it is Java-serialized binary. To reset teleport points/guardian angels, stop the server and delete it (which also loses hunter applications).

---

Multiplayer, worlds and compatibility

How many players does it support? Where is the cost?

Every second the timer:

1. schedules one synchronous task per online player (advanceTime);
2. runs a four-piece armor legality check per player.

That is O(online players) synchronous work per second. Dozens of players are fine; at hundreds this is the main cost. Everything runs on the main thread through the Bukkit API and cannot be moved to async.

How do I disable supernatural rules in one world?

1. Set MultiWorld: true;
2. Revoke supernatural.world.enabled in that world with a permissions plugin.

The permission defaults to true, so without revoking it everything is enabled. The plugin does not decide by world name.

What if another plugin conflicts?

• This plugin handles damage at NORMAL and observes deaths at MONITOR; if the damage event is already cancelled by another plugin, it returns immediately.
• Its only WorldGuard interaction is the PVP and MOB_SPAWNING flags.
• It is not hard-bound to any permissions plugin; it only logs “found xxx”.
• When two plugins both modify damage, the final value depends on priority order; move one before or after the other and test.

---

Testing and development

The test server ports are taken?

Defaults are game port 25565 and control port 25566. If another server is already running:

mvn -Pit package exec:java -Dit.gamePort=25570 -Dit.controlPort=25571

For mvn verify -Pit, pass the ports to the forked JVM:

mvn verify -Pit -DargLine="-Dit.gamePort=25572 -Dit.controlPort=25573"

mvn verify -Pit is slow or fails?

The first run downloads Paper and server dependencies, so slow is normal. On failure, read:

target/it/server/console.log

Common causes:

• the JDK is not 25;
• the network cannot reach the Paper download site;
• 25565/25566 are occupied;
• exec:java was run without packaging first (The plugin under test has not been built.).

In the manual hall, “clicking a board does nothing”?

• Only specific boards are triggers; decorative and explanatory boards do nothing.
• You are too far away (roughly beyond 4 blocks).
• The red wool on the west wall is the exit button, not a board.
• The guide NPC needs a right-click and can be clicked repeatedly.

I changed the code, restarted the test server, and nothing changed?

The test server copies target/mmSupernaturals.jar, and that jar is produced by mvn package. Restarting without repackaging always loads the old plugin.

rm -f target/mmSupernaturals.jar
mvn -Pit package
mvn -Pit package exec:java

---

Known limitations and deliberate trade-offs

These are behaviours the current version either keeps on purpose or has not covered yet. Know them before deploying:

1. An angel has no in-game cure. Only /sn cure works.
2. The enderborn death counter is in memory. Relogging resets it.
3. [none] means “no weapon restriction”. That is the default for vampire, priest and demon.
4. The sign-up system is not strict admission control. With EnableJoinCommand on, /sn join writes the name into the in-memory whitelistYaml.yml configuration object but never calls save, so entries that were never saved are lost on restart. The conversion check also only blocks “a non-human converting again”, not a human’s first conversion. Use a permissions plugin if you need strict control.
5. Configuration is not migrated. New keys are read from built-in defaults and never written into an old config.yml.
6. Power and teleport points are not written in real time. A crash can roll them back; run /sn save after important changes.
7. The power cap is hard-coded at 10,000. Configuration can change starting values, not the cap.
8. The church altar is lethal to non-priest supernaturals. That is the implementation; the church is not a safe zone.
9. Supernatural.SpreadChance does not cover the enderborn. It uses EnderBorn.Convert.Chance.
10. /sn killlist is not class-locked. A non-hunter only gets a warning; the list is printed anyway.
11. A weapon ban cannot be narrowed to one item. Since 1.5.1 a tiered name means its whole tier and its paired tier, in every kind — twelve items. Banning exactly one sword would need a code change.
12. A new tier is not covered automatically. A new kind is (the lists are generated from MaterialTiers and a tier the game extends is picked up), but a new tier — the next material above netherite — only enters the defaults when somebody names it.
13. The angel’s armour and animal rules are hard-coded. GOLDEN/DIAMOND/NETHERITE and “no paired weapon on animals” live in AngelManager, not in config.yml.