主配置

plugins/CloudTitle/config.yml，修改后 /clt reload（数据库设置需要重启服务端）。

基础

# 没有佩戴称号时显示的称号 ID（必须是已定义的称号）；留空则变量返回空白
default-title: ''
# 称号图片前自动加上的颜色代码，默认 &f；留空 '' 则不加
glyph-color: '&f'
# 切换称号的冷却（秒），0 = 不限制
switch-cooldown-seconds: 3

# 称号未单独设置时使用的默认值
defaults:
  fps: 8            # GIF 未设 fps 时使用 GIF 自己的帧延迟
  height: 16        # %clt_use% 大图高度
  small-height: 8   # %clt_use_small% 小图高度

为什么默认加 &f

称号图片本质上是一个文字，会继承周围的样式：物品名称与 lore 默认是斜体、lore 默认是紫色，没有颜色代码时称号图片会变斜或被染色。 glyph-color: '&f' 会在菜单、称号卡、变量与 API 输出的每个称号图片前自动加上白色（= 图片原本的颜色）并取消斜体，不需要在模板里手动写 &f。

菜单

menu:
  main-on-command: true       # /clt 打开主菜单；false = 直接打开称号仓库
  preview:                    # 右键试戴预览
    enabled: true
    seconds: 3
    variant: big
    title: ''
    actionbar: '&7预览 &f{name} &8· &7{seconds} 秒后返回'
  progress-bar:               # {progress} 进度条
    length: 10
    full: '&a■'
    empty: '&8■'

菜单的布局、按钮与音效在 menus/*.yml，见菜单。

获得提示

notify: 设置获得称号时的屏幕标题、动作栏、音效、全服公告、后台指令与自动佩戴，见获得提示。

属性、药水与粒子

stats:
  mode: equipped    # equipped 佩戴才生效 / owned 拥有即生效 / none 关闭
effects:
  mode: equipped
  show-icon: true
particles:
  enabled: true
  hide-when-invisible: true
buff-disabled-worlds: []   # 这些世界里属性、药水、粒子都不生效

见属性加成、粒子与药水效果。

自定义称号

custom-title: 设置价格、长度、外框、颜色权限、黑名单、数量上限等，见自定义称号。

称号卡

card:
  material: PAPER
  custom-model-data: 0
  item-model: ''
  name: '&6称号卡 &8· &r{name}'
  lore: ['{preview}', '', '{lore}', '&7时长：&e{time}', '{stats}', '', '&e右键使用']
  glow: true

每个称号也可以在自己的 card: 中单独覆盖材质与模型，见称号卡。

操作日志

log:
  keep-days: 90     # 保留天数，0 = 永久保留
  equip: false      # 是否也记录佩戴 / 卸下（数量较多）

聊天

chat:
  hover:            # %clt_use_hover% 与 API 的悬停文本
    - '{name}'
    - '{lore}'
    - '{stats}'
    - '&7{expire}'

{expire} 在永久称号上显示 messages.yml 的 time-permanent，限时称号显示 hover-expire（剩余 X）。

没有聊天插件时，可以让云称号直接把称号加在聊天消息前面：

chat:
  prefix:
    enabled: false        # 已有聊天插件请保持 false，改用 %clt_use_static% / %clt_use_hover%
    format: '{title} '
    variant: small        # small 小图（推荐）/ big 大图
    hover: true           # 悬停显示上面的 hover 文本
    click-showcase: true  # 点击称号打开该玩家的称号展示

数据库

database:
  type: sqlite          # sqlite 或 mysql（MariaDB 也填 mysql）
  file: data.db
  host: 127.0.0.1
  port: 3306
  database: minecraft
  username: root
  password: ''
  parameters: 'useSSL=false&serverTimezone=Asia/Shanghai&characterEncoding=utf8'
  table-prefix: clt_
  pool-size: 4

SQLite：单服默认，无需任何设置。
MySQL 8 / MariaDB：多个服务器共用时使用。插件自带连接池并已内置于 jar 中，启动时不需要从网络下载任何依赖；MySQL / SQLite 驱动由 Paper 自带。
MySQL 8 使用 caching_sha2_password 且未开 SSL 时，parameters 需加上 allowPublicKeyRetrieval=true。
所有数据库读写都在独立线程执行，不会卡主线程。
数据表：clt_players（佩戴）、clt_owned（拥有）、clt_log（日志）、clt_changes（跨服同步）。

跨服同步

多个分流共用同一个 MySQL 时，一个服务器上的变更（给予、购买、佩戴、到期……）会在几秒内同步到玩家当前所在的服务器，不需要重新进服。

sync:
  enabled: auto          # auto = 使用 MySQL 时开启；true / false
  interval-seconds: 3    # 检查间隔
  server-id: ''          # 留空自动生成，仅用于区分变更来源

例如：玩家在生存服，管理员在大厅执行 /clt give，称号会在约 1 – 3 秒内出现在玩家的仓库与变量中；收回时也会自动卸下。
玩家切换服务器时本来就会重新读取数据，不受同步间隔影响。
同步只用一张很小的表，每次检查是一条带索引的查询，对数据库几乎没有负担；超过 1 小时的同步记录会自动清理。
各服务器的 titles/ 与 frames/ 建议保持一致（可用同步工具或共享目录），否则某些称号只在部分服务器存在。

资源包

resource-pack:
  output: resource_pack
  zip: true
  glyph-start: 'F0000'
  merge: { … }

见资源包与合并。

更换数据库

从 SQLite 换到 MySQL（或反过来）：

在 database: 里把两边的设置都填好（file 与 host / port / username …），type 先不改。
执行 /clt convert mysql（或 sqlite），全部玩家、拥有记录、奖励领取记录、自定义称号与日志会复制过去；目标里已有的同一条记录会被覆盖。
把 type 改成新的数据库，重启服务器。

其他文件

文件	内容
`categories.yml`	称号分类，见分类与筛选
`rewards.yml`	收集奖励，见收集奖励
`stats.yml`	属性、药水效果、粒子样式在菜单里的显示名称
`messages.yml`	全部提示消息（更新后新增的消息会自动使用默认值）
`menus/*.yml`	7 个菜单，见菜单

基础​

菜单​

获得提示​

属性、药水与粒子​

自定义称号​

称号卡​

操作日志​

聊天​

数据库​

跨服同步​

资源包​

更换数据库​

其他文件​

基础

菜单