PhantomControl

PhantomControl is a lightweight phantom management plugin for Minecraft Paper and Folia servers. It lets players choose whether phantoms can spawn for them while giving administrators central controls for individual players, batches, and world rules.

Language: Chinese README

Features

• Personal phantom control – Players can enable, disable, or check their own phantom spawning.
• Administrator management – Manage another player's status, run batch operations, and view server statistics.
• Paper and Folia support – Built against the Paper API, with Folia-aware scheduling and environment detection.
• FlatFile and MySQL storage – Choose local file storage or a remote MySQL database.
• World whitelist and blacklist – Restrict phantom control to selected worlds or exclude selected worlds.
• Automatic saving and cache cleanup – Periodically save player data and clean expired cache entries.
• Hot configuration reload – Reload messages, GUI settings, world rules, and database settings without restarting. Command names and aliases require a restart.
• GUI controls – Give players a simple inventory interface for changing their status.
• Chinese and English – Automatically follow the player's client language or force a language in configuration.
• PlaceholderAPI support – Expose phantom status to scoreboards, tab lists, and other integrations.
• Developer API and events – Read or change status from other plugins and listen for changes or blocked spawns.
• bStats and debug tools – Optional anonymous usage statistics, detailed debug logging, and configuration validation.

Requirements

• Minecraft 1.20.1 or newer
• Paper or Folia server

Spigot and Bukkit servers are not supported.

Installation

1. Download PhantomControl-2.1.1.jar from the latest release.
2. Place the JAR in your server's plugins folder.
3. Restart the server. PhantomControl will create its default configuration files.
4. Edit the configuration as needed and run /phantomcontrolreload (or /pcr) to apply reloadable settings.

Paper and Folia load HikariCP and the MySQL driver through the server's library system; no separate dependency installation is required.

Configuration

The main configuration is plugins/PhantomControl/config.yml. Messages are stored separately in plugins/PhantomControl/messages.yml and messages_en.yml.

Database

database:
  type: "flatfile" # flatfile or mysql
  auto-save-interval: 300 # seconds; 0 disables automatic saving
  cache-timeout-minutes: 60
  mysql:
    address: "localhost:3306"
    username: "username"
    password: "password"
    database: "phantom_control"
    prefix: "phc_"

World rules

whitelist:
  world-whitelist-enabled: false
  world-whitelist: []
  world-blacklist-enabled: true
  world-blacklist: []

When the whitelist is enabled, only listed worlds are controlled. When the blacklist is enabled, listed worlds are ignored.

Messages, language, GUI, and debug

settings:
  message:
    default-type: "CHAT" # CHAT, ACTION_BAR, or TITLE
    show-title-on-change: false
    show-actionbar-on-change: false
    language:
      mode: "auto" # auto, chinese, or english
      default: "messages_en"
  bstats:
    enabled: true
  debug:
    enabled: false

GUI materials and command names can also be customized under settings.gui and settings.commands. Command names and aliases are registered at startup, so changing them requires a server restart.

Example GUI material settings:

settings:
  gui:
    status-enabled-material: "GREEN_WOOL"
    status-disabled-material: "RED_WOOL"
    enable-button-material: "LIME_DYE"
    disable-button-material: "RED_DYE"
    info-button-material: "BOOK"
    border-material: "GRAY_STAINED_GLASS_PANE"

Commands

Main command aliases: /phantomcontrol, /pc, /phantom.

Player commands

Administrator commands

Permissions

Players without phantomcontrol.use are automatically kept enabled by the plugin's permission enforcement.

PlaceholderAPI

PlaceholderAPI is optional. Version 2.11.7 or newer is recommended for Folia environments.

Developer API

PhantomControl registers PhantomControlAPI through Bukkit's ServicesManager.

import org.bukkit.Bukkit;
import yyz.chl.phantomcontrol.api.PhantomControlAPI;

PhantomControlAPI api = Bukkit.getServicesManager().load(PhantomControlAPI.class);
if (api == null) return;

boolean enabled = api.arePhantomsEnabled(player);
api.setPhantomsEnabled(player, false);

For offline UUID operations, use the asynchronous overloads:

api.arePhantomsEnabled(playerId).thenAccept(enabled -> {
    Bukkit.getLogger().info("Phantoms enabled: " + enabled);
});

api.setPhantomsEnabled(playerId, false).thenAccept(success -> {
    Bukkit.getLogger().info("Saved: " + success);
});

Available events:

• PhantomStatusPreChangeEvent – Fired before a change and can be cancelled.
• PhantomStatusChangeEvent – Fired after a successful change; includes the old state, new state, and PhantomStatusChangeSource.
• PhantomSpawnBlockedEvent – Fired when PhantomControl blocks a phantom spawn.

Example event listener:

import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import yyz.chl.phantomcontrol.event.PhantomStatusPreChangeEvent;

public class PhantomListener implements Listener {
    @EventHandler
    public void onPreChange(PhantomStatusPreChangeEvent event) {
        if (!event.willBeEnabled()
                && event.getPlayer().hasPermission("server.need.phantom")) {
            event.setCancelled(true);
        }
    }
}

FAQ

Why are phantoms still spawning?

Check the world's whitelist/blacklist rules, confirm that PhantomControl loaded without errors, and check for another plugin that changes phantom spawning.

Does PhantomControl change the player's sleep statistics?

No. The plugin blocks phantom spawning through Paper events and does not modify the player's TIME_SINCE_REST statistic.

How do I disable bStats?

Set settings.bstats.enabled to false and reload the configuration.

How do I enable debug logging?

Set settings.debug.enabled to true, then reload the configuration. Detailed diagnostics will be written to the console.

bStats

PhantomControl uses bStats for anonymous server and plugin usage statistics. Data collection can be disabled with settings.bstats.enabled: false.

Links and contact

• Source code
• Issue tracker
• License: GNU AGPL v3.0
• QQ group: 1093090518
• Author QQ: 2919089965

If PhantomControl helps your server, consider leaving a star on GitHub or reporting suggestions and issues through the issue tracker.