Companions-Max
数据与变量
配置文件、YAML/MySQL 数据保存、内置语言变量及 PlaceholderAPI。
数据与变量
配置文件
| 文件 | 用途 |
|---|---|
config.yml | 常规设置、世界限制、数据库、兑换券 |
companions.yml | 随从定义 |
gui/gui.yml、gui/companions.yml | 独立界面配置 |
lang.yml | 消息与帮助 |
customability.yml | 自定义能力参数 |
companionsdata.yml | YAML 模式的玩家拥有记录、当前随从与硬币 |
settings.saveTime 单位为分钟。YAML 保存使用主线程快照和后台写入，不能把这个间隔当成额外备份；定期备份整个插件目录。
settings.cancelKeyWord 默认 取消，用于玩家改名/改武器流程。管理员编辑器的取消词当前固定为 取消。
settings.disabledWorlds 阻止在指定世界使用随从。
settings.packetSearchRange 当前按逗号加空格拆分，保留默认 10, 10, 10 的格式。
MySQL
默认使用 YAML：
database:
use: false
hostname: localhost
port: 3306
username: "root"
password: ""
databaseName: "companions"
tablePrefix: "companions_"
使用 MySQL 时填入自己的数据库信息、切换 use: true，停服重启使连接池配置生效。
切换存储方式不等于自动迁移玩家数据；当前没有一键 YAML 与 MySQL 双向迁移工具。先备份、验证数据，再切换正式环境。
源码中包含 MySQL Connector/J 8.4.0 和 HikariCP 4.0.3。老 Java/旧数据库组合需要实测，不能仅以插件 core 的 Java 8 字节码推断驱动可用。
内置变量
内置变量按具体消息或菜单替换，不是任意配置字段的全局模板引擎。
| 使用位置 | 变量 |
|---|---|
| 随从商店描述 | %companion%、%companion_l%、%price% |
| 已拥有/详情描述 | %active_companion%、%active_companion_l%、%companions_coins%、%tbacommand_duration% |
| 玩家详情标题 | %target%、%target_l% |
| 其他语言消息 | 对照 lang.yml 原有占位符，不要假定能使用全部变量 |
商店显示名称字段不承诺替换上述描述变量；建议直接填写独立中文名称。
PlaceholderAPI
安装 PlaceholderAPI 后由插件内置扩展注册，标识为 companions：
| 变量 | 返回内容 |
|---|---|
%companions_activecompanion% | 当前随从标识，无当前随从时为 NONE |
%companions_companionlevel% | 当前随从等级；未装备时可返回 NOT EQUIPPED |
%companions_companionname% | 当前随从自定义名称；未装备时可返回 NOT EQUIPPED |
%companions_companioncoin% | 随从硬币 |
%companions_companionsize% | 已拥有缓存数量 |
当前实现按在线 Player 处理，不支持可靠的离线玩家解析。请只在在线玩家上下文使用这些变量；历史拥有记录保留时，数量也可能包含已删除定义的记录。
这些 %companions_...% 变量与商店内部 %companion% 不是同一套替换机制。