Installation

Get PhantomBans running on your server in a few minutes.

Requirements

Need	Detail
Server software	Paper, or a Paper fork like Purpur
Minecraft version	1.21 or newer
Java	21 or newer
Internet on first start	Yes, to download a few libraries (one time)

PhantomBans needs Java 21 or newer and Paper 1.21 or newer. Older servers will not load it.

Install steps

Stop the server

Shut the server down fully before adding any plugin.

Drop in the jar

Move the PhantomBans jar into your server’s plugins/ folder.

Start the server (with internet)

Start the server. On the first start, PhantomBans downloads a few libraries from the internet, so make sure the machine can reach the web. After that first start, they are cached and no connection is needed.

Check the console

You should see the PhantomBans start banner and no errors. If anything goes wrong, the console will tell you.

First run

On the first start PhantomBans creates its config files and a database. With the default settings it uses a local SQLite file, so there is nothing else to set up. You can begin punishing right away, then come back and tune the config when you are ready.

Plugin folder layout

After the first start your folder looks like this:

- - config.yml
  - appearance.yml
  - screens.yml
  - messages.yml
  - templates.yml
  - data.db

File	What it holds
`config.yml`	Core settings: database, general options, GeoIP, defaults, Discord, GUI.
`appearance.yml`	Chat formatting and punishment broadcast messages.
`screens.yml`	The disconnect screens players see (ban, kick, and so on).
`messages.yml`	All other in-game text.
`templates.yml`	Punishment ladders for repeat offences.
`data.db`	The SQLite database (only when using SQLite).

Optional integrations

PlaceholderAPI→

Adds PhantomBans placeholders you can use in other plugins.

Discord→

Sends punishments, reports, and appeals to your Discord channels.

PlaceholderAPI and Vault are soft-depends. The plugin works without them, and uses them if they are present.

Ready to make it yours? Head to Configuration.