猹件开发组

Appearance

On this page

服务端基础配置 ​

plugins/ChaUI/config.yml 管理持久槽数据库、页面目录、打开成功提示、客户端要求和游戏窗口限制。页面内容写在 pages/，共享变量和通用脚本写在 global-scripts.yml，不放在本文件中。

完整配置 ​

下面包含当前默认配置的全部字段。数据库默认关闭；要保存跨重启的持久槽物品，请先填写自己的连接信息，再将 enable 改为 true。

yaml
database:
  # 是否启用持久槽 MySQL。修改本分区后完整重启服务端。
  enable: false
  # 数据库名称
  schema: "cha_plugin"
  # 示例默认账号和密码，启用前替换为自己的数据库凭据。
  username: "root"
  password: "root"
  # 数据库地址和端口
  host: "localhost"
  port: "3306"
  # true 时按 ChaCore 规则共用连接池；false 时使用独立连接池。
  share: false
  # 持久槽变化合并写入数据库的间隔，单位为秒，最低为 5。
  flush-interval: 30

# 相对于 plugins/ChaUI/ 的页面目录
pages-folder: pages
# 相对于 plugins/ChaUI/ 的页面备份目录
backup-folder: backups/pages

# 可选游戏窗口限制，两种格式不能混写；默认不配置。
# 固定尺寸（禁止拖拽）：window-size: ["1920x1080", "1280x720"]
# 固定比例（允许拖拽）：window-size: ["4:3", "16:9"]

notifications:
  # 是否向指令发送者显示“页面打开成功”提示
  page-opened: true

client-requirement:
  # true 时只允许完成 ChaUIMod 就绪握手的玩家进入
  require-mod: false
  # 等待 client_ready 的 tick 数，20 tick 约为 1 秒，允许 20~600
  ready-timeout-ticks: 100

client-requirement.require-mod 默认关闭。打开后，玩家进入服务器时必须在配置的等待时间内完成协议匹配的 client_ready；未安装 ChaUIMod、协议不匹配或握手格式无效时会收到语言文件中的中文原因并被移出。等待时间会限制在 20..600 tick。修改后执行 /chaui reload，在线玩家会按新设置重新检查；这项功能不新增网络通道。

限制游戏窗口尺寸或比例 ​

在配置根层级添加 window-size 字符串列表，就能统一玩家的游戏窗口。只影响 Minecraft 主窗口，ChaUI 外置编辑器仍可自由调整大小。

固定分辨率：例如只允许玩家使用 1920×1080 或 1280×720：

yaml
window-size:
  - "1920x1080"
  - "1280x720"

玩家不能拖动窗口边框调整大小，原版“视频设置”中的分辨率项改为服务器提供的“窗口尺寸”选项。

固定比例：例如允许 4:3 和 16:9：

yaml
window-size:
  - "4:3"
  - "16:9"

玩家可以拖动窗口边框，但宽高比保持不变。原版“视频设置”提供“窗口比例”和宽度调整，高度自动计算并显示。拖动宽度滑块时先预览数值，松开后应用窗口大小。

全屏时按当前选项的比例居中显示完整游戏画面，多余空间填充黑边，画面不会拉伸或裁掉边缘；黑边不接受点击或滚轮。固定尺寸模式进入全屏后使用该尺寸对应的比例，退出全屏后恢复所选窗口尺寸。

保存后执行 /chaui reload，已就绪的在线客户端会收到更新，之后进入的玩家也会应用该配置。客户端会记住最后收到的合法限制及选择，断开服务器、返回主菜单和重启游戏后继续生效。另一台服务器下发新配置时覆盖旧限制；未下发配置的旧服务端不会清除它。

要取消限制，删除 window-size，或改为 window-size: [] 后重载。客户端收到取消通知后恢复自由调整大小，保留当时的窗口尺寸。

配置写错时如何处理 ​

  • 一份列表只能使用一种格式，不能把 "1920x1080" 和 "4:3" 混写。比例值也必须用引号包住。
  • 固定尺寸的宽、高均为 320..16384 的整数；比例分子、分母为 1..10000 的整数，并且应能在上述尺寸范围内组成窗口。宽度调整范围会随比例变化。
  • 最多配置 32 项；重复尺寸和等价比例会合并，例如 16:9 与 32:18 是同一个选项。
  • 非字符串、空字符串、格式错误、超范围或混写会在控制台报告具体项目，本次修改不生效，继续使用上一次合法配置。首次启动没有合法配置时不限制窗口。

如果退出服务器后窗口仍不能自由拖动，这是已保存限制仍在生效。由服务器移除配置并重载、让客户端收到取消通知即可恢复；仅断线或重启不会清除限制。

让持久槽跨重启保存 ​

persistent 表示按玩家和槽位 ID 共享状态；是否写入数据库由 database.enable 决定。默认的 false 只保留本次服务器进程中的物品，关闭页面再打开可以恢复，但服务器重启后不会恢复。

  1. 准备可用的 MySQL 数据库和账号，填写 schema、username、password、host、port。
  2. 在 ChaCore 的 config.yml 中确认 depend 包含 database_mysql。
  3. 将 ChaUI 的 database.enable 改为 true，完整重启服务器；/chaui reload 不会重新建立数据库连接。
  4. 查看启动和玩家登录日志，确认没有持久槽存储或读取失败提示，再投入使用。

玩家登录时读取持久槽，交互先更新内存，再按 flush-interval 合并保存；玩家退出和正常停服时也会提交剩余变化。slot.yml 只登记允许使用的槽位及物品规则，不能用它备份玩家物品。数据库保存范围只有 persistent 虚拟槽；临时槽、背包映射槽和原版容器不由这项设置保存。

连接失败或玩家数据读取失败时，对应持久槽会降级为本次进程内保存，并在日志中给出警告；不能把“页面还能打开”当成数据库已经保存成功。请先处理日志中的连接或读取问题。旧的内存数据不会自动作为历史数据库记录导入。

槽位注册和页面写法见槽位注册表与物品槽。

关闭页面打开成功提示 ​

把 notifications.page-opened 改为 false，保存后执行 /chaui reload。普通页面、子页面和固定位置世界页面的打开指令便不再向指令发送者发送 lang.yml 中的 page-opened 提示。也可以把这条语言文本留空。

这项开关只控制这条成功消息。页面打开失败、编辑器错误以及使用其他消息项的操作仍会正常反馈。完整打开语法见指令说明。

页面与备份目录 ​

pages-folder 和 backup-folder 都应使用 plugins/ChaUI/ 内的相对路径，不能跳出插件目录。修改前先停服并备份，按新位置迁移已有页面，再重启；改配置不会替你移动文件。

默认示例的生成规则见服务端安装指南：只在启动时默认 pages/ 整个目录不存在时生成整套示例。删除某一个示例文件或清空现有目录不会自动补回。