PremiumUUID
一个轻量级的 Paper 插件,用于在 online-mode=false 的服务器上解析正版(Mojang)UUID,通过将玩家昵称与 Mojang API 进行匹配来实现。
在离线模式服务器中,每位玩家都会被分配一个离线 UUID,这会破坏拥有正版 Minecraft 账户的玩家的游戏连续性——背包、统计数据以及权限都绑定在一个与其真实账户不对应的 UUID 上。PremiumUUID 会检测某个昵称是否属于现有的正版账户,如果是,则在登录时分配该账户的真实 Mojang UUID,从而保持跨会话的连续性。
重要通知
本插件不验证账户所有权。 它仅检查昵称是否在 Mojang 服务器上存在为正版账户,不会对连接的玩家进行身份认证。因此,任何未经验证的玩家都可以使用任意正版昵称加入服务器,并获得该账户的 UUID,以及其完整的背包、统计数据和权限访问权。
本插件适用于私有的、可信的服务器,其中每位玩家都是已知的。 它不能替代正确的身份验证机制,不应在公共或半公共服务器上使用。
快速开始
- 下载并将 jar 文件放入服务器的
plugins/ 文件夹中。
- 确保服务器以离线模式运行(
server.properties 中的 online-mode=false),此插件仅在离线模式服务器上有意义。
- 重启服务器。这将在
plugins/PremiumUUID/ 内生成 config.yml、uuid-cache.yml 和 overrides.yml。
功能
- 自动 UUID 解析:通过
AsyncPlayerPreLoginEvent 实现,注册优先级为最低
- 持久化磁盘缓存(
uuid-cache.yml),支持可配置的 TTL(生存时间)
- 按昵称覆盖(
overrides.yml):可以为特定昵称强制开启或关闭正版检查,独立于全局设置
- 优雅降级 —— API 故障绝不会阻止登录;过期的缓存条目或离线 UUID 将作为回退方案
- 管理命令:用于重新加载配置、检查玩家状态、清除缓存和管理覆盖项
- 禁用时无开销:由单个配置标志控制
就是这样——插件默认启用,并在下一次登录时开始解析正版 UUID。
配置
plugins/PremiumUUID/config.yml:
premium-uuid-enabled: true
mojang-api:
timeout-ms: 3000
cache:
file: "uuid-cache.yml"
ttl-minutes: 1440 # 24 小时
fallback:
log-warning: true
logging:
level: "INFO" # INFO | DEBUG
| 键 |
描述 |
默认值 |
premium-uuid-enabled |
插件逻辑的主开关 |
true |
mojang-api.timeout-ms |
HTTP 请求超时时间,单位为毫秒 |
3000 |
cache.file |
插件数据文件夹内的缓存文件名 |
uuid-cache.yml |
cache.ttl-minutes |
缓存条目重新验证前的时间 |
1440 |
fallback.log-warning |
当回退到离线 UUID 时记录警告日志 |
true |
logging.level |
INFO 用于高层决策,DEBUG 用于 API 调用详情 |
INFO |
命令
基础命令:/premiumuuid(别名:/puuid)
权限:premiumuuid.admin(默认:op)
| 命令 |
描述 |
/premiumuuid reload |
无需重启服务器即可重新加载 config.yml |
/premiumuuid status <nick> |
显示玩家的缓存状态及单独覆盖项 |
/premiumuuid clearcache [nick] |
清除整个 UUID 缓存,或单个条目 |
/premiumuuid enable <nick> |
即使 premium-uuid-enabled 为 false,也强制对该昵称执行正版检查 开启 |
/premiumuuid disable <nick> |
即使 premium-uuid-enabled 为 true,也强制对该昵称执行正版检查 关闭 —— 玩家始终使用离线 UUID 登录,不进行缓存查找或 API 调用 |
/premiumuuid reset <nick> |
移除该昵称的任何覆盖项,将其重置为默认值(unset) |
按昵称覆盖
覆盖项存储在 plugins/PremiumUUID/overrides.yml 中,并在重启后保留:
overrides:
steve: true # 始终运行正版检查
alex: false # 始终使用离线 UUID
昵称在存储前会被规范化为小写。命令具有幂等性,玩家无需先加入服务器,其覆盖项就可以预先配置好。
登录时的优先级:
overrides.yml 中的单个覆盖项优先于其他所有内容。
- 全局
premium-uuid-enabled 设置仅在不存在覆盖项时适用。
PremiumUUID
A lightweight Paper plugin that resolves premium (Mojang) UUIDs on online-mode=false servers, matching player nicknames against the Mojang API.
On offline-mode servers, every player is assigned an offline UUID, which breaks account continuity for players who own a legitimate copy of Minecraft — inventories, statistics, and permissions all remain tied to a UUID that doesn't correspond to their real account. PremiumUUID detects when a nickname belongs to an existing premium account and, when it does, assigns that account's real Mojang UUID at login, preserving continuity across sessions.
IMPORTANT NOTICE
This plugin does not verify account ownership. It only checks whether a nickname exists as a premium account on Mojang's servers, it performs no authentication of the connecting player. As a result, any unauthenticated player can join with any premium nickname and will be granted that account's UUID, along with full access to its inventory, statistics, and permissions.
This plugin is intended for private, trusted servers where every player is known. It is not a substitute for proper authentication and should not be used on public or semi-public servers.
Quick Start
- Download and drop the jar into your server's
plugins/ folder.
- Make sure the server runs in offline mode (
online-mode=false in server.properties), this plugin only makes sense on offline-mode servers.
- Restart the server. This generates
config.yml, uuid-cache.yml, and overrides.yml inside plugins/PremiumUUID/.
Features
- Automatic UUID resolution via
AsyncPlayerPreLoginEvent, registered at lowest priority
- Persistent disk cache (
uuid-cache.yml) with a configurable TTL
- Per-nickname overrides (
overrides.yml) to force the premium check on or off for a specific nickname, independent of the global setting
- Graceful degradation — API failures never block a login; a stale cache entry or the offline UUID is used as a fallback
- Administrative commands for reloading configuration, inspecting player status, clearing the cache, and managing overrides
- Zero overhead when disabled, controlled by a single configuration flag
That's it — the plugin is enabled by default and starts resolving premium UUIDs on the next login.
Configuration
plugins/PremiumUUID/config.yml:
premium-uuid-enabled: true
mojang-api:
timeout-ms: 3000
cache:
file: "uuid-cache.yml"
ttl-minutes: 1440 # 24 hours
fallback:
log-warning: true
logging:
level: "INFO" # INFO | DEBUG
| Key |
Description |
Default |
premium-uuid-enabled |
Master toggle for the plugin's logic |
true |
mojang-api.timeout-ms |
HTTP request timeout, in milliseconds |
3000 |
cache.file |
Cache filename within the plugin's data folder |
uuid-cache.yml |
cache.ttl-minutes |
Time before a cache entry is revalidated |
1440 |
fallback.log-warning |
Log a warning when falling back to the offline UUID |
true |
logging.level |
INFO for high-level decisions, DEBUG for API call details |
INFO |
Commands
Base command: /premiumuuid (alias: /puuid)
Permission: premiumuuid.admin (default: op)
| Command |
Description |
/premiumuuid reload |
Reloads config.yml without a server restart |
/premiumuuid status <nick> |
Displays the cached state and individual override for a player |
/premiumuuid clearcache [nick] |
Clears the entire UUID cache, or a single entry |
/premiumuuid enable <nick> |
Forces the premium check on for that nickname, even when premium-uuid-enabled is false |
/premiumuuid disable <nick> |
Forces the premium check off for that nickname, even when premium-uuid-enabled is true — the player always logs in with an offline UUID, with no cache lookup or API call |
/premiumuuid reset <nick> |
Removes any override for that nickname, resetting it to default (unset) |
Per-nickname overrides
Overrides are stored in plugins/PremiumUUID/overrides.yml and persist across restarts:
overrides:
steve: true # always runs the premium check
alex: false # always uses the offline UUID
Nicknames are normalized to lowercase before being stored. Commands are idempotent, and a player does not need to have joined the server before for an override to be pre-configured on their behalf.
Precedence at login:
- An individual override in
overrides.yml takes priority over everything else.
- The global
premium-uuid-enabled setting applies only when no override is present.
评论 0
登录后参与评分
还没有评论,来抢沙发吧