Home

mmSupernaturals

A Paper plugin that gives players a race: everyone starts as an ordinary human until something turns them into something else.

Eight supernatural races — Vampire, Ghoul, Werewolf, Demon, Priest, WitchHunter, Angel and EnderBorn — each with its own abilities, its own way of turning people, and its own counters. Most of them also have a way back to humanity. Nearly every active ability costs Power; the cap is 10,000, and anything that scales with power scales linearly with the current amount.

Item	Value
Current version	1.5.0
Server	Paper 26.3 (api-version: 26.3)
Java	25
Build	Maven (mvn package)
License	GPL-3.0
Requirements	None hard; WorldGuard is an optional soft dependency (softdepend)

This is a community-maintained fork. The project began in 2011 as the Bukkit plugin Supernatural Players by Matt “Matterz” Walker, later edited by mmiillkkaa. The original repository and its download page are gone; FaeyUmbrea kept an archived fork alive, and VampireAchao moved it to Maven and modern Paper and maintains it today.

---

What problem it solves

Vanilla PvP is symmetrical: two players with the same sword deal the same damage. mmSupernaturals breaks that symmetry and replaces it with asymmetric identities plus a resource economy:

• Every race has a clear strength (werewolf night fighting, ghoul damage soaking, witch hunter archery, demon fire) and a clear price (sunlight, water, daytime, armor, weapon restrictions).
• Turning is not a menu click. It is something that happens in the world: build an altar, die under specific conditions, be killed by a specific mob, or slay three different kinds of supernatural.
• Turning back also costs something: another altar, a brewed potion, or drowning in icy water while carrying snowballs.
• The races form a food chain: priests suppress the supernatural, witch hunters hunt it, the supernatural hunts humans, and humans can be turned.

---

Core features

• Nine identities: Human (the starting point) plus Vampire, Ghoul, Werewolf, Demon, Priest, WitchHunter, Angel and EnderBorn.
• Power-driven: kills, food, lava, water, and the passage of time all feed or drain different races in different ways.
• Altars and rituals: gold for the bite, lapis for the cure, diamond for ordination; materials and surrounding-block counts are configurable.
• Truces: vampires are at peace with 41 hostile mobs by default, ghouls with 6 undead types; attacking one breaks the truce for 120 seconds.
• Bounties: witch hunters start with five random targets; completing one immediately draws another.
• Guardian Angel: a priest can turn one lethal hit into a full-health survival.
• Multiple churches: a server can register any number of churches; a priest altar only answers within 10 blocks of one.
• A real test harness: unit tests plus scenario tests that boot an actual Paper server and drive fake players through complete flows.

---

Quick start (30 seconds)

1. Download mmSupernaturals-1.5.0.jar from Releases and drop it into your server’s plugins/ directory.
2. Start Paper 26.3 on Java 25. The plugin writes its own config.yml; no command is needed to begin playing.
3. In game, run /sn classes to see the races and /sn power to see your own race and power.
4. As an admin, add two locations: stand at the church and run /sn setChurch; stand at the banish destination and run /sn setBanish.

Full instructions: Installation.

---

Documentation map

What you want to know	Read
What the project is and how it plays	This page + Features
How to install, build, and run the test server	Installation
How the code is organized, what the core classes do, how events flow	Architecture
What every key in config.yml means and its default	Configuration
Which commands exist and which permissions they need	Commands and Permissions
How to complete a turning, a ritual, or a bounty step by step	Usage
Why an ability did nothing, or why power never drops	FAQ

---

Versions and compatibility

• The plugin depends only on the Paper API and, optionally, WorldGuard. No database, no network service, no other hard dependency.
• plugin.yml declares api-version: 26.3; older servers will refuse to load it.
• Permissions are checked through Bukkit’s SuperPerms. PermissionsEx, GroupManager, bPermissions and PermissionsBukkit are detected only to print a log line; the check itself does not change.
• When WorldGuard is present, the plugin reads the PVP and MOB_SPAWNING flags of the region a player stands in. When it is absent, both are treated as allowed.

---

Contributing

Issues and pull requests are welcome. Before submitting, run:

mvn test          # unit tests
mvn verify -Pit   # scenario tests (boots a real Paper server; slow)

A release is a tag that matches the version in pom.xml (for example v1.5.1). GitHub builds the jar and generates release notes from the commits.

License

GNU General Public License v3.0. See gpl-3.0.txt in the repository root.