PhantomControl
PhantomControl 是一款适用于 Minecraft Paper 和 Folia 服务器的轻量级幻翼管理插件。它允许玩家自行选择是否为自己生成幻翼,同时为管理员提供了针对单个玩家、批量操作以及世界规则的集中控制功能。
语言: 中文说明
功能特性
- 个人幻翼控制 – 玩家可以启用、禁用或查看自己的幻翼生成状态。
- 管理员管理 – 管理其他玩家的状态,执行批量操作,并查看服务器统计数据。
- 支持 Paper 和 Folia – 基于 Paper API 构建,具备 Folia 感知调度和环境检测功能。
- FlatFile 与 MySQL 存储 – 可选择本地文件存储或远程 MySQL 数据库。
- 世界白名单与黑名单 – 将幻翼控制限制在选定的世界中,或排除选定的世界。
- 自动保存与缓存清理 – 定期保存玩家数据并清理过期的缓存条目。
- 热重载配置 – 无需重启即可重载消息、GUI 设置、世界规则和数据库设置。命令名称和别名需要重启才能生效。
- GUI 控制界面 – 为玩家提供简单的物品栏界面以更改其状态。
- 中英文支持 – 自动跟随玩家的客户端语言,或在配置中强制指定语言。
- PlaceholderAPI 支持 – 将幻翼状态暴露给记分板、标签页列表和其他集成工具。
- 开发者 API 与事件 – 允许其他插件读取或更改状态,并监听状态变更或生成被阻止的事件。
- bStats 与调试工具 – 可选的匿名使用统计信息、详细的调试日志记录以及配置验证功能。
依赖要求
- Minecraft 1.20.1 或更高版本
- Paper 或 Folia 服务器
不支持 Spigot 和 Bukkit 服务器。
安装步骤
- 从最新版本发布页面下载
PhantomControl-2.1.1.jar。
- 将该 JAR 文件放入服务器的
plugins 文件夹中。
- 重启服务器。PhantomControl 将创建其默认配置文件。
- 根据需要编辑配置文件,并运行
/phantomcontrolreload(或 /pcr)以应用可重载的设置。
Paper 和 Folia 通过服务器的库系统加载 HikariCP 和 MySQL 驱动程序;无需单独安装依赖项。
配置
主配置文件位于 plugins/PhantomControl/config.yml。消息内容分别存储在 plugins/PhantomControl/messages.yml 和 messages_en.yml 中。
数据库
database:
type: "flatfile" # flatfile 或 mysql
auto-save-interval: 300 # 秒数;设为 0 则禁用自动保存
cache-timeout-minutes: 60
mysql:
address: "localhost:3306"
username: "username"
password: "password"
database: "phantom_control"
prefix: "phc_"
世界规则
whitelist:
world-whitelist-enabled: false
world-whitelist: []
world-blacklist-enabled: true
world-blacklist: []
当启用白名单时,仅对列出的世界进行控制。当启用黑名单时,将忽略列出的世界。
消息、语言、GUI 和调试
settings:
message:
default-type: "CHAT" # CHAT, ACTION_BAR, 或 TITLE
show-title-on-change: false
show-actionbar-on-change: false
language:
mode: "auto" # auto, chinese, 或 english
default: "messages_en"
bstats:
enabled: true
debug:
enabled: false
GUI 材质和命令名称也可以在 settings.gui 和 settings.commands 下进行自定义。命令名称和别名为启动时注册,因此更改它们需要重启服务器。
示例 GUI 材质设置:
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"
命令
主要命令别名:/phantomcontrol、/pc、/phantom。
玩家命令
| 命令 |
描述 |
权限 |
/pc enable 或 /pc on |
为你自己启用幻翼生成 |
phantomcontrol.use |
/pc disable 或 /pc off |
为你自己禁用幻翼生成 |
phantomcontrol.use |
/pc toggle 或 /pc switch |
切换你的幻翼生成状态 |
phantomcontrol.use |
/pc status 或 /pc check |
检查你当前的状态 |
phantomcontrol.use |
/pc gui 或 /pc menu |
打开图形控制菜单 |
phantomcontrol.use |
/pc help |
显示命令帮助 |
phantomcontrol.use |
管理员命令
| 命令 |
描述 |
权限 |
/pc admin enable <player> |
为某玩家启用幻翼 |
phantomcontrol.admin |
/pc admin disable <player> |
为某玩家禁用幻翼 |
phantomcontrol.admin |
/pc admin status <player> |
检查某玩家的状态 |
phantomcontrol.admin |
/pc admin batch enable <player1> <player2> ... |
为多名玩家启用幻翼 |
phantomcontrol.admin |
/pc admin batch disable <player1> <player2> ... |
为多名玩家禁用幻翼 |
phantomcontrol.admin |
/pc admin server |
查看在线玩家状态统计 |
phantomcontrol.admin |
/phantomcontrolreload, /pcr, /phreload |
重载插件配置 |
phantomcontrol.reload |
权限
| 权限 |
描述 |
默认值 |
phantomcontrol.use |
使用玩家控制命令 |
所有人 |
phantomcontrol.admin |
使用管理员命令 |
操作员 (OP) |
phantomcontrol.reload |
重载插件配置 |
操作员 (OP) |
没有 phantomcontrol.use 权限的玩家会被插件的权限强制机制自动保持启用状态。
PlaceholderAPI
PlaceholderAPI 为可选依赖。在 Folia 环境下推荐使用 2.11.7 或更高版本。
| 占位符 |
描述 |
示例 |
%phantomcontrol_enabled% |
玩家幻翼是否已启用 |
true / false |
%phantomcontrol_status% |
本地化状态文本 |
Enabled / Disabled |
Developer API
PhantomControl 通过 Bukkit 的 ServicesManager 注册了 PhantomControlAPI。
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);
对于离线 UUID 操作,请使用异步重载方法:
api.arePhantomsEnabled(playerId).thenAccept(enabled -> {
Bukkit.getLogger().info("Phantoms enabled: " + enabled);
});
api.setPhantomsEnabled(playerId, false).thenAccept(success -> {
Bukkit.getLogger().info("Saved: " + success);
});
可用的事件:
PhantomStatusPreChangeEvent – 在状态变更前触发,可被取消。
PhantomStatusChangeEvent – 在变更成功后触发;包含旧状态、新状态以及 PhantomStatusChangeSource。
PhantomSpawnBlockedEvent – 当 PhantomControl 阻止幻翼生成时触发。
事件监听器示例:
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
为什么幻翼仍在生成?
请检查世界的白名单/黑名单规则,确认 PhantomControl 已无错误加载,并排查是否有其他插件改变了幻翼的生成行为。
PhantomControl 会更改玩家的睡眠统计数据吗?
不会。该插件通过 Paper 事件阻止幻翼生成,并不会修改玩家的 TIME_SINCE_REST 统计值。
如何禁用 bStats?
将 settings.bstats.enabled 设置为 false,然后重新加载配置。
如何启用调试日志?
将 settings.debug.enabled 设置为 true,然后重新加载配置。详细的诊断信息将写入控制台。
bStats
PhantomControl 使用 bStats 收集匿名的服务器和插件使用统计数据。可以通过设置 settings.bstats.enabled: false 来禁用数据收集。
链接与联系方式
如果 PhantomControl 对你的服务器有所帮助,欢迎在 GitHub 上留下星标,或通过问题追踪器提交建议和问题。
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
- Download
PhantomControl-2.1.1.jar from the latest release.
- Place the JAR in your server's
plugins folder.
- Restart the server. PhantomControl will create its default configuration files.
- 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
| Command |
Description |
Permission |
/pc enable or /pc on |
Enable phantom spawning for yourself |
phantomcontrol.use |
/pc disable or /pc off |
Disable phantom spawning for yourself |
phantomcontrol.use |
/pc toggle or /pc switch |
Toggle your phantom spawning status |
phantomcontrol.use |
/pc status or /pc check |
Check your current status |
phantomcontrol.use |
/pc gui or /pc menu |
Open the graphical control menu |
phantomcontrol.use |
/pc help |
Show command help |
phantomcontrol.use |
Administrator commands
| Command |
Description |
Permission |
/pc admin enable <player> |
Enable phantoms for a player |
phantomcontrol.admin |
/pc admin disable <player> |
Disable phantoms for a player |
phantomcontrol.admin |
/pc admin status <player> |
Check a player's status |
phantomcontrol.admin |
/pc admin batch enable <player1> <player2> ... |
Enable phantoms for multiple players |
phantomcontrol.admin |
/pc admin batch disable <player1> <player2> ... |
Disable phantoms for multiple players |
phantomcontrol.admin |
/pc admin server |
View online player status statistics |
phantomcontrol.admin |
/phantomcontrolreload, /pcr, /phreload |
Reload plugin configuration |
phantomcontrol.reload |
Permissions
| Permission |
Description |
Default |
phantomcontrol.use |
Use player control commands |
Everyone |
phantomcontrol.admin |
Use administrator commands |
Operator |
phantomcontrol.reload |
Reload plugin configuration |
Operator |
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.
| Placeholder |
Description |
Example |
%phantomcontrol_enabled% |
Whether the player's phantoms are enabled |
true / false |
%phantomcontrol_status% |
Localized status text |
Enabled / Disabled |
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
If PhantomControl helps your server, consider leaving a star on GitHub or reporting suggestions and issues through the issue tracker.
评论 0
登录后参与评分
还没有评论,来抢沙发吧