CatCraftTitle

CatCraftTitle

中文 | English

插件作用

CatCraftTitle 是一个轻量级、支持 GUI 管理、中英双语、功能完善的 Minecraft 头衔与后缀管理插件，支持 MySQL / PostgreSQL / SQLite 三种数据库，帮助服务器轻松实现玩家头衔系统，并支持跨服同步。

内置商店系统（可用内置金币或 Vault 经济）、每日签到、基于 PlaceholderAPI 的自动称号、Tab/头顶显示与 RGB 渐变。

本次更新使用了 DeepSeek V4.1 Flash。

settings:
  check-update: true
  update-check-interval-hours: 6   # 更新检测间隔（小时）
  update-notify-console: true      # 发现新版本是否在控制台打印横幅
  update-notify-ops: true          # 发现新版本是否在聊天栏通知 op / 管理员

功能特点

• 多级头衔体系：每个玩家可拥有多个头衔，按 ID 独立管理，自由切换启用
• 独立后缀系统：头衔与后缀分离设计，玩家可单独控制每个后缀的启用/关闭
• 图形化 GUI 管理：玩家可通过 /catcraft gui 打开直观的界面管理所有称号
• 管理员 GUI 控制面板：/titleadmin panel 查看真实 TPS/在线/内存、切换语言、开关功能、重载配置
• 自动称号系统：基于 PlaceholderAPI 占位符，按等级、金币、击杀数等自动授予/收回称号，支持 >= <= == != > <
• 实时语言切换：GUI 面板一键中英文切换，消息即时生效
• 独立功能开关：RGB 渐变、商店、属性支持、Tab 显示、聊天格式均独立开关
• 跨服数据同步：支持 MySQL / PostgreSQL，多服务器共享玩家数据
• 本地存储备选：MySQL/PostgreSQL 连接失败自动回退 SQLite，数据不丢失
• 无需重启修改：管理员可直接修改头衔显示名，即时生效
• 玩家自助管理：玩家可通过指令或 GUI 管理自己的头衔和后缀
• 默认头衔系统：无头衔玩家显示可配置的默认头衔
• RGB 渐变色支持：渐变色可自定义，支持十六进制颜色
• 完全国际化：中文/英文一键切换，文案可在消息文件中自由修改
• PlaceholderAPI 支持：提供 %catcraft_title%、%catcraft_suffix%、%catcraft_balance% 等变量
• 内置商店与金币系统：支持内置金币或 Vault 经济，每日签到可获得金币
• 不可售卖的头衔：商品支持「可购买 / 展示但不可购买 / 完全隐藏」三态，可写备注（如「活动限定」）
• 强大的自动称号条件：且/或/非、区间、字符串、正则、数值容错，并内置 30+ 变量（不依赖 PlaceholderAPI）
• 启动信息看板：控制台显示版本、作者、数据库、PAPI/Vault、调度器状态

注意事项

• PlaceholderAPI 不是必需的：只有「自动称号」与占位符变量需要它。
• Vault 不是必需的：只有 shop.currency: vault 需要它。
• 从旧版本升级时不需要删除 config.yml，插件会自动补全新选项并保留你的注释与设置。
• 离线（非正版）服务器完全支持：面板里按名字搜索离线玩家时，插件会先查自己的 player_names 名字缓存；离线服还会按 Minecraft 的「离线 UUID」规则直接匹配玩家名（UUID.nameUUIDFromBytes("OfflinePlayer:名字")），不依赖 usercache.json。
• 离线服注意：玩家改名后会得到新的 UUID（这是离线模式的机制），旧称号仍留在原 UUID 名下。
• 本插件需要 Java 8 或更高的服务端运行环境；构建需要 JDK 17+（Gradle wrapper 已升级到 9.3.0，兼容较新的 JDK）。

头衔以及后缀统一管理 - GUI 界面

管理员 GUI 控制面板

兼容服务端

• 支持：Paper 1.16.x ~ 26.3、Purpur 1.16.x ~ 26.3、Spigot 1.16.x ~ 26.3
• 支持：Folia 1.19.4 ~ 26.3（Folia 自 1.19.4 起提供）
• 不支持：Bukkit（不推荐）、Sponge / BungeeCord / Velocity

Folia 上的显示说明：Folia 1.19.x 的记分板队伍 API 尚未开放（registerNewTeam 会抛异常），
插件的 Tab/头顶显示会自动降级为「Tab 名字前缀」，并在控制台打印一次提示；聊天称号格式、
GUI、头衔/后缀功能不受影响。服务端版本较新的 Folia 若已支持记分板，则自动使用完整显示。

兼容数据库

• MySQL（驱动已内置）
• PostgreSQL（驱动已内置）
• SQLite（驱动已内置）

必要前置

玩家指令

管理员指令（需 catcraft.admin 权限）

控制面板与维护

头衔管理

后缀管理

商店管理

类型：0 表示头衔，1 表示后缀。

权限节点

以上权限名都可以在 config.yml 的 permissions 段改成你服务器现有的权限名。

PlaceholderAPI 变量

配置文件（自动生成，示例）

config-version: 9          # 请勿手动修改（插件据此自动补充新选项）
language: zh               # zh / en

database:
  type: sqlite             # mysql / postgresql / sqlite（连接失败自动回退 sqlite）
  mysql:
    host: localhost
    port: 3306
    db: your_db
    user: your_user
    pass: your_pass
  postgresql:
    host: localhost
    port: 5432
    db: your_db
    user: your_user
    pass: your_pass
  sqlite:
    file: catcraft.db

permissions:               # 可改成你服务器现有的权限名
  admin: "catcraft.admin"
  use: "catcraft.use"
  shop: "catcraft.shop"

settings:
  debug: false
  enable-rgb: false
  gradient-colors:         # 1 段纯色或多段平滑渐变
    - "FF0000"
    - "FF00FF"
    - "8000FF"
  default-title: "&d[&d萌新喵]&7"   # 留空则不显示默认头衔
  attribute-support: false
  auto-check-interval: 30  # 自动称号检查间隔（秒）
  check-update: true
  update-check-interval-hours: 6   # 每隔几小时自动检查一次更新
  update-notify-console: true      # 发现新版本时在控制台提示
  update-notify-ops: true          # 发现新版本时在聊天栏通知在线管理员
  messages-file: true

chat:
  enabled: true
  format: "{title}{name}{suffix}: {message}"
  override-format: true    # false = 只在原版格式下接管
  display-name: true       # Tab 列表 + 头顶昵称显示称号

shop:
  enabled: false
  currency: internal       # internal / vault
  default-balance: 0       # 新玩家初始金币
  signin-reward: 30        # 每日签到奖励（0 = 只记录签到、不发金币）
  # 商品的三态与备注不需要写在配置里，用指令或管理面板设置：
  #   状态  /titleadmin shop state <ID> <类型> <sellable|display|hidden>
  #         sellable = 可购买 | display = 展示但不可购买 | hidden = 商店中完全隐藏
  #   备注  /titleadmin shop note <ID> <类型> <文本>（如「活动限定」，填 clear 清空）

# 自动称号规则（仅当 settings.attribute-support 为 true 时生效）
#
# 条件写法（1.6.0）：
#   数值比较 : %player_level% >= 30      也支持 <= == != > < 与反向写法 30 <= %player_level%
#              另外接受 SQL 风格写法 => =< <>（含义分别是 >= <= !=）
#   且 / 或  : %a% >= 10 && %b% < 5      || 表示或，! 表示非，可用括号改变优先级
#   区间     : {level} in 10..30          not in 10..30 表示不在区间内
#   字符串   : %job% equals 战士          contains / startsWith / endsWith / matches(正则)
#              matches 为整串匹配：%world% matches world 不会命中 world_nether，模糊匹配请写 world.*
#              比较运算符右侧解析为空时一律判为不满足（避免变量写错导致全服都拿到称号）
#   真值判断 : %some_flag%                非空且不是 false/no/0/off/无/否 即为真（0 / 0.0 / 0% 都算假）
# 变量写法：
#   %xxx% —— PlaceholderAPI 变量（需要装 PlaceholderAPI 与对应插件）
#   {xxx} —— 插件内置变量，不需要 PAPI：{level} {health} {food} {playtime_minutes}
#            {kills} {deaths} {balance} {titles} {online_players} {hour}
#            {perm:权限节点} {has_title:ID} 等
# 数值容错：1,234 / 85% / 物理攻击 120 这类文本都能正确解析
# 排查问题：/titleadmin autotest <玩家>
auto-rules:
  - id: 1
    type: 0                # 0=头衔，1=后缀
    display: "&6[&e老手&6]"
    condition: "%player_level% >= 30"
  - id: 2
    type: 1
    display: " &8[&7大佬&8]"
    condition: "%vault_eco_balance% > 1000"
  - id: 3                  # 只用内置变量，不需要 PlaceholderAPI
    type: 0
    display: "&b[&f冒险者&b]"
    condition: "{level} in 10..30 && {playtime_minutes} > 1440"
  - id: 4                  # 属性插件变量 + 内置变量 + 权限判断混用
    type: 1
    display: " &8[&6VIP&8]"
    condition: "{perm:group.vip} == true || %ap_attack% > 500"

数据库结构

CREATE TABLE player_titles (
    uuid VARCHAR(36) NOT NULL,
    title_id INT NOT NULL,
    title_display VARCHAR(255) NOT NULL,
    type INT DEFAULT 0,       -- 0=头衔, 1=后缀
    is_active BOOLEAN DEFAULT FALSE,
    is_auto BOOLEAN DEFAULT FALSE,  -- 1.4.0 新增：是否由自动规则授予
    PRIMARY KEY (uuid, title_id)
);

CREATE TABLE shop_items (
    id INT NOT NULL,
    type INT NOT NULL,        -- 0=头衔商品, 1=后缀商品
    display VARCHAR(255) NOT NULL,
    price INT NOT NULL,
    state INT NOT NULL DEFAULT 0,        -- 1.5.0 新增：0=可购买, 1=仅展示, 2=隐藏
    note VARCHAR(128) NOT NULL DEFAULT '', -- 1.5.0 新增：备注（如「活动限定」）
    PRIMARY KEY (id, type)    -- 1.4.0：旧表（主键只有 id）会在启动时自动迁移，数据不丢
);

CREATE TABLE player_balances (
    uuid VARCHAR(36) PRIMARY KEY,
    balance INT NOT NULL DEFAULT 0
);

CREATE TABLE player_names (           -- 1.6.0 新增：玩家名缓存（面板搜索/离线服显示用）
    uuid VARCHAR(36) PRIMARY KEY,
    name VARCHAR(32) NOT NULL,
    last_seen BIGINT NOT NULL DEFAULT 0
);

CREATE TABLE player_signin (
    uuid VARCHAR(36) PRIMARY KEY,
    last_signin BIGINT NOT NULL DEFAULT 0
);

所有表在插件首次启动时自动创建；旧版本的表结构会在启动时自动迁移，无需手动操作。

从源码构建

./gradlew build          # 产物在 build/libs/CatCraftTitle-x.y.z.jar

适配新的 Minecraft 版本时，只需要修改 build.gradle 里的 spigotApiVersion（例如 26.3-R0.1-SNAPSHOT），然后重新执行上面的命令即可。

• Gradle wrapper 已升级到 9.3.0（旧版 8.10.2 在 JDK 24+ 上会直接构建失败）。
• 构建出的 jar 已包含 MySQL / PostgreSQL / SQLite 驱动，不需要再额外安装驱动。
• 推送 v1.6.0 这样的 tag 时，GitHub Actions 会自动构建并发布 Release（工作流见 .github/workflows/build.yml）。

常见问题

Q：玩家没有头衔时显示什么？
A：显示 settings.default-title 配置的内容，留空则什么都不显示。

Q：MySQL/PostgreSQL 连接失败怎么办？
A：插件会自动回退到 SQLite 并在控制台提示，数据不会丢；修好数据库连接后重载即可。

Q：支持 RGB 颜色吗？
A：支持。开启 `settings.enable-r