MythicExchange 使用文档

插件介绍

不是骗，是等价交换

——炼金术师如是说。

MythicExchange 是一款基于 GUI 界面的物品兑换插件，专为 Paper 1.20+ 服务器打造。管理员可以在游戏内通过拖拽物品来配置兑换方案（没错，不用写一行配置文件），玩家打开界面后一键兑换，干净利落。

支持多页翻页、每日兑换限制、自定义界面布局、ItemsAdder 贴图标题，甚至还能多个服务器共用一个数据库——如果你真的闲到搞了一个服务器集群的话。

说人话：上面放代价，下面放奖励，玩家点一下就换了。

主要功能

可视化编辑 —— 管理员直接在 GUI 里拖物品，关闭自动保存，不用碰配置文件（除了第一次）
Shape 布局系统 —— 用字符画的方式定义界面长什么样，支持完全自定义装饰物品和 CustomModelData
多页翻页 —— 一页放不下？翻页就是了，理论上可以无限页（硬盘够大就行）
每日兑换限制 —— 防止肝帝把你的经济系统干碎
ItemsAdder 标题支持 —— 支持 %img_offset_-8% 偏移语法，让你的 GUI 标题看起来高大上
MySQL 数据库 —— 支持 MySQL 5.7+，多服务器共享数据
异步操作 —— 所有数据库操作都在异步线程执行，不会卡你的主线程（20TPS 保卫战）

命令列表

主命令：/mec（别名：/mythicexchange、/exchange）

命令	说明	权限
`/mec create <ID>`	创建一个新的兑换 GUI 并立即进入编辑模式	`mec.admin`
`/mec edit <ID> [页码]`	编辑已有的兑换 GUI，可指定页码	`mec.admin`
`/mec delete <ID>`	删除一个兑换 GUI（不可撤销，想好了再删）	`mec.admin`
`/mec list`	列出所有已创建的兑换 GUI	`mec.admin`
`/mec open <ID> [玩家]`	打开兑换 GUI，可以帮别人打开	`mec.use`（帮别人开需要 `mec.admin`）
`/mec reload`	重载配置文件和 Shape 布局	`mec.admin`
`/mec setlimit <ID> <槽位> <限制> [页码]`	设置某个槽位的每日兑换限制（-1 = 无限制）	`mec.admin`
`/mec settitle <ID> <标题格式\|none>`	设置 GUI 的自定义标题格式（none 清除）	`mec.admin`
`/mec setoffset <ID> <偏移量>`	设置标题的 ItemsAdder 偏移量	`mec.admin`

输入 /mec 不带参数会显示帮助信息，别慌。

权限节点

权限	说明	默认
`mec.admin`	管理员权限，可以创建/编辑/删除 GUI、重载配置等	OP
`mec.use`	玩家权限，可以打开和使用兑换 GUI	所有人

目前本插件不提供 PlaceholderAPI 占位符。如果你特别需要（比如在计分板上显示今日兑换次数之类的），可以联系作者提需求。

使用教程

创建一个兑换 GUI

/mec create 我的兑换站 —— 会自动打开编辑界面。

放入物品

在编辑界面中，第 2 行放代价物品（玩家需要消耗的），第 4 行放奖励物品（玩家会得到的）。同一列上下对应就是一组兑换方案。

关闭界面

直接按 ESC 关闭，自动保存。没有保存按钮这种多余的东西。

让玩家使用

/mec open 我的兑换站 —— 或者让玩家自己输入，或者你用其他插件（比如 NPC 插件）绑定这个命令。

设置每日兑换限制

想限制玩家每天只能兑换 3 次某个物品？

方法一：GUI 操作

在编辑模式下，对着你想限制的物品 Shift + 右键，会打开按钮设置界面，在里面调整每日限制。

方法二：命令

/mec setlimit 我的兑换站 27 3 —— 第 27 号槽位（第 4 行第 1 格），每日限制 3 次。设为 -1 取消限制。

翻页

在编辑模式下，点击下一页按钮会自动创建新页并保存当前页。页数理论上没有上限，取决于你有多少东西想让玩家换。

配置文件

插件的配置文件在 plugins/MythicExchange/config.yml，首次启动会自动生成。

数据库配置

YAMLconfig.yml

database:
  host: localhost          # 数据库地址
  port: 3306               # 端口
  database: mythic_exchange # 数据库名（需要提前创建好）
  username: root           # 用户名
  password: ""             # 密码（建议别用 root 空密码，真的）
  pool-size: 10            # 连接池大小，一般不用改
  connection-timeout: 5000 # 连接超时（毫秒）

通用设置

YAMLconfig.yml

settings:
  cache-ttl: 60            # 缓存时间（暂未启用，留着好看的）
  default-title: "§6§l兑换商店"  # 新建 GUI 的默认标题
  default-offset-amount: 0.0     # 新建 GUI 的默认偏移量

标题支持 %img_offset_-8% 占位符，需要安装 ItemsAdder 才能生效。没装的话会自动去掉这个占位符，不会报错。

Shape 布局

这是本插件最好玩的部分——用字符画定义 GUI 布局：

YAMLconfig.yml

gui:
  shape:
    'XXXXXXXXX'    # 第 1 行：装饰
    'CCCCCCCCC'    # 第 2 行：代价物品槽
    'AAAAAAAAA'    # 第 3 行：箭头装饰
    'RRRRRRRRR'    # 第 4 行：奖励物品槽
    'XXXXXXXXX'    # 第 5 行：装饰
    'PP##I##NN'    # 第 6 行：翻页 + 信息

特殊字符（写死在代码里的）

字符	含义
`C`	代价物品槽——玩家需要消耗的物品放这里
`R`	奖励物品槽——玩家会得到的物品放这里
`#`	空槽位——编辑模式下可以放东西，玩家模式下显示为空
`P`	上一页按钮
`N`	下一页按钮

自定义装饰字符

X、A、I 这些是装饰字符，你可以用任意字母，然后在 gui.items 里定义它们的外观：

YAMLconfig.yml

gui:
  items:
    'X':                          # 对应 shape 里的 X
      material: GRAY_STAINED_GLASS_PANE
      name: ' '                   # 空格 = 没有名字
      custom_model_data: -1       # -1 表示不设置
    'A':
      material: ARROW
      name: '&e→'
      lore: []
      custom_model_data: -1
    'P':
      material: ARROW
      name: '&e&l上一页'
      lore:
        - '&7点击查看上一页'
      custom_model_data: -1
    'N':
      material: ARROW
      name: '&e&l下一页'
      lore:
        - '&7点击查看下一页'
      custom_model_data: -1
    'I':
      material: BOOK
      name: '&b&l兑换说明'
      lore:
        - '&7第2行是代价，第4行是奖励'
        - '&7点击奖励物品即可兑换'
      custom_model_data: -1

每个装饰字符都支持 custom_model_data，可以配合资源包做出花里胡哨的界面。

标题设置

YAMLconfig.yml

gui:
  title:
    custom_title_enabled: true
    title_format: "§f%img_offset_-8%§f§6§l兑换商店"
    offset_amount: 4.0              # 偏移量，0~8 之间
    fallback_title: "§6§l兑换商店"  # ItemsAdder 没装时用这个

消息配置

所有发给玩家的消息都可以自定义，支持 & 颜色代码：

YAMLconfig.yml

messages:
  prefix: "&8[&6MythicExchange&8] "
  no-permission: "&c你没有权限执行此操作"
  gui-created: "&a成功创建兑换GUI: &e{id}"
  gui-deleted: "&a成功删除兑换GUI: &e{id}"
  gui-not-found: "&c找不到兑换GUI: &e{id}"
  exchange-success: "&a兑换成功!"
  exchange-no-items: "&c你没有足够的物品进行兑换"
  exchange-limit: "&c你今天已达到兑换上限 ({count}/{limit})"

依赖插件与版本

插件	是否必须	说明
Paper 1.20.1	必须	服务端核心，Spigot 理论上也行但没测试（出了问题找我）
MySQL 5.7+	必须	数据库，需要提前建好库
ItemsAdder	可选	用于 GUI 标题的贴图偏移效果，没有也能正常运行

技术信息

项目	信息
插件名称	MythicExchange
版本	1.0
服务端	Paper 1.20.1
Java 版本	17+
API 版本	1.20
数据库	MySQL 5.7+（通过 HikariCP 4.0.3 连接池）
MySQL 驱动	mysql-connector-java 8.0.33

常见问题

这是 JDBC URL 的字符集参数问题，已在 1.0 版本修复。如果你用的是旧版本，检查 DatabaseManager.java 里的 characterEncoding 参数，应该是 UTF-8 而不是 utf8mb4。

执行 /mec reload 重载配置。偏移量从配置文件实时读取，reload 之后立即生效。

/mec edit <ID> 重新打开编辑模式，随便拖。关闭自动保存，不需要你做额外操作。

不支持。你去找 Geyser 的麻烦吧，这不是我的锅。

目前不行。既然都搞 Minecraft 服务器了，装个 MySQL 也不过分吧？

如果你看到这里还没关掉文档，说明你是个认真的服主。祝你的服务器人满为患，经济系统不崩。

MythicExchange ¥68

插件介绍

不是骗，是等价交换

主要功能

命令列表

权限节点

使用教程

创建一个兑换 GUI

放入物品

关闭界面

让玩家使用

设置每日兑换限制

方法一：GUI 操作

方法二：命令

翻页

配置文件

数据库配置

通用设置

Shape 布局

特殊字符（写死在代码里的）

自定义装饰字符

标题设置

消息配置

依赖插件与版本

技术信息

常见问题