Skip to content

Installation

Jump to bottom
VampireAchao edited this page Oct 17, 2026 · 1 revision

Installation

This page covers four things: installing on a production server, building from source, what to do after the first start, and how to use the repository’s test server for manual testing.

1. Requirements

Item Requirement Notes
Server Paper 26.3 plugin.yml pins api-version: 26.3; Spigot or older Paper will refuse to load it
Java 25 maven.compiler.release=25; the runtime needs 25 as well
Build tool Maven 3.9+ Only needed when building from source
Permissions plugin Recommended The plugin uses Bukkit SuperPerms; it runs without one (defaults are in Commands and Permissions)
WorldGuard Optional softdepend; used for the PVP and MOB_SPAWNING region flags

No database, network service, or other hard dependency is required.

2. Installing a release

  1. Download mmSupernaturals-1.5.0.jar from Releases.
  2. Place it in the server’s plugins/ directory.
  3. Start the server. A line like mmSupernaturals version 1.5.0 enabled. means it loaded.
  4. On first start, the plugin creates the following under plugins/mmSupernaturals/:
plugins/mmSupernaturals/
├── config.yml          # every tunable setting (defaults written on first start)
├── VERSION             # the plugin version last loaded
├── data.yml            # player race and power (created on first save)
├── storage.dat         # teleport points / guardian angels / hunter applications (Java serialization)
└── whitelistYaml.yml   # sign-up list (only appears when it is actually saved; /sn join does not save it)

data.yml and storage.dat do not necessarily appear on the first start: the first is written on the first conversion/cure/save, the second on shutdown. whitelistYaml.yml behaves the same way; its absence does not prevent startup.

3. First-start setup

The plugin is playable without any setup — everyone is human. To make the priest altar and the banish spell work, an admin needs two locations:

Step Command Purpose
1 Stand at the church altar and run /sn setChurch Registers a church (clears every previously registered church)
2 Stand at the banish destination and run /sn setBanish Sets where the priest’s Banish spell sends its target
3 (optional) /sn church add Registers another church; a server can have any number
4 (optional) Place an iron door with a sign reading WitchHunter Creates a WitchHunter hall entrance

Things that are easy to get wrong:

  • A church is a location, not a block. A diamond-block altar only answers within 10 blocks (X/Y/Z each ±10) of a registered church.
  • /sn setChurch clears the old churches. To keep several, use /sn church add, inspect with /sn church list, remove the nearest with /sn church remove, and wipe everything with /sn church clear.
  • Without a banish point, Banish refuses to cast and costs nothing (1.5.0 says so explicitly).
  • The WitchHunter sign is matched within a 5×5×5 box around the iron door. Any line containing WitchHunter.Hall.Message (default WitchHunter) is enough.

4. Building from source

You need JDK 25 and Maven.

git clone https://github.com/VampireAchao/mmSupernaturals.git
cd mmSupernaturals

mvn package

The output is not in target/ but in server/plugins/ beside the project:

server/plugins/mmSupernaturals.jar

That comes from plugin.output.dir in pom.xml (${project.basedir}/server/plugins), which makes it convenient to replace the jar on a local test server. server/ is listed in .gitignore and is never committed.

The -Pit profile redirects the output to target/:

mvn -Pit package
# → target/mmSupernaturals.jar

If a rebuilt jar still behaves like the old code, check its timestamp first. maven-jar-plugin decides whether to rebuild from timestamps in the output directory; deleting the old jar before packaging is the reliable fix.

5. Tests

Unit tests

mvn test

These include:

  • PluginDescriptorTest: the main class exists, api-version is declared, and the sn command is registered.
  • SuperNPlayerPowerTest: power bounds and NaN handling.
  • SaveFilePowerTest: hand-edited power / superPower values are clamped back to 0–10000.

Scenario tests (integration)

mvn verify -Pit

These tests:

  1. Prepare a real Paper server under target/it/server/ (downloading paper.jar on the first run).
  2. Install target/mmSupernaturals.jar and the test-only mmHarness.jar.
  3. Start the server in a fixed-seed superflat world.
  4. Drive clientless fake players over a local control port through complete flows such as “build the altar → right-click → become a vampire → use the cure altar to turn back”.

See Architecture for the classes and the protocol.

Manual test server

mvn -Pit package exec:java

This compiles, packages, and starts a server you can join:

Item Value
Game address localhost:25565 (offline mode, any name)
Control port 25566 (internal to the harness, not a game port)
Console Type server commands in the same terminal, e.g. op YourName
Stop Ctrl+C (the world is saved)

The test server generates real terrain by default; add -Dit.flat=true for the superflat world used by the scenario tests.

The manual server also builds a test hall: eight boards on the lobby wall, one per race. Right-click a board to enter that race’s own world. Each room is one step of the flow; the boards are the actions (right-click), and the guide NPC can be right-clicked repeatedly for the long explanation.

Useful switches:

Property Effect
-Dit.keepServer=true Leave the server running after the tests finish
-Dit.keepState=true Keep the world and plugin data between runs
-Dit.flat=true Use the fixed superflat world (the scenario default)
-Dit.seed=<n> Reuse a manual world seed
-Dit.debug=true Open JDWP on 5005 for remote plugin debugging
-Dit.debugPort=<n> Pick the debug port (it walks upward if the port is taken)
-Dit.debugSuspend=true Hold the server at startup until a debugger attaches to onEnable
-Dit.gamePort=<n> / -Dit.controlPort=<n> Change ports so several servers can share a machine

exec:java does not compile or package anything by itself. Always use mvn -Pit package exec:java; exec:java alone refuses to start because there is no jar to load.

To change ports for mvn verify -Pit, pass them to the forked JVM:

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

6. Upgrading

  1. Back up plugins/mmSupernaturals/ (at least data.yml and config.yml).
  2. Stop the server, replace the jar, and start it again.

Things to know about configuration upgrades:

  • Defaults are written only when config.yml does not exist. An existing file is never extended or migrated.
  • A key added in a new version is read from its built-in default when it is missing from an old file (for example, EnderBorn.Convert.Chance defaults to 0.1 in 1.5.0). To make new keys appear in the file, delete config.yml, let it regenerate, then reapply your custom values.
  • Since 1.5.0, data.yml clamps power read from disk back to 0–10000 and logs a WARNING whenever it had to correct a value.

7. Uninstalling

  1. Stop the server and delete plugins/mmSupernaturals.jar.
  2. To remove all data as well, delete plugins/mmSupernaturals/.

Deleting the data directory loses player races, power, teleport points, guardian angels and hunter applications together. To reset only race/power, edit data.yml; teleport points and guardian angels live in storage.dat, which can only be reset as a whole.

8. Build and startup troubleshooting

Symptom Cause Fix
The plugin under test has not been built. exec:java was run without packaging first Use mvn -Pit package exec:java
Paper server jar is missing and could not be downloaded. The first run needs network access to download Paper Check the network/proxy, or place paper.jar at target/it/server/paper.jar manually
no answer on port 25566 within PT3M The server failed to start, or the port is taken Read target/it/server/console.log; check whether 25565/25566 are in use
Unsupported class file major version Building with a JDK older than 25 mvn -version; point JAVA_HOME at JDK 25
The server refuses to load the plugin Not Paper 26.3 Look for the api-version error; use a matching server or change plugin.api.version and rebuild
The manual server cannot be joined Port conflict, or the whitelist is on The harness writes white-list=false and online-mode=false; confirm no other server owns the port

Next: read Features for the nine races, or go straight to Usage to perform a turning.

Overview

Reference

Practice

Clone this wiki locally