⚙️ 配置文件 config.yml 详解
QinhCoreLib（下称 QCL）只有一个主配置文件：plugins/QinhCoreLib/config.yml。它在首次启动时自动生成默认内容，本页逐段逐项讲清每个键的默认值、可选值、作用、改完之后是 /qcl reload 即可还是必须重启服务器。
📌 通用规则：凡涉及数据库连接方式切换、模块开关的改动，都建议重启服务器最稳妥；纯数值/开关（如 debug、economy 默认源、javascript 调试）大多
/qcl reload即可。具体每项下方都有标注。
🗂️ 完整 config.yml 原文
下面是 QCL 1.2.0 默认生成的完整内容，可直接作为照抄模板：
yaml
database:
type: sqlite # sqlite 或 mysql
sqlite:
data-folder: data # 相对插件目录的数据文件夹
mysql:
host: localhost
port: 3306
database: qinhcorelib
username: root
password: ""
debug:
enabled: false
prefix: "[QinhCoreLib-Debug]"
economy:
default-provider: auto # auto|vault|excellenteconomy|ee|playerpoints|pp。auto：有 currency 时优先 EE，否则 Vault>EE>PlayerPoints
default-currency: money # EE 货币 id（money/silver/gold…），Vault/PlayerPoints 忽略
javascript:
enabled: true
default-function: main # 脚本引用不带函数名时调用的默认函数
debug:
print-stacktrace: false
attribute: # 属性后端选择（全生态统一从这里读）
backend: native # native（自带原生属性，无需属性插件）| attributeplus | auto
modules: # 可禁用不需要的模块（默认全 true）
config: true
database: true
reflection: true
modelengine: true
customcrops: true
craftengine: true
mythicmobs: true
neigeitems: true
mmoitems: true
gui: true
action: true
pdc: true
item: true
hologram: true
scheduler: true
condition: true
expression: true
script: true
economy: true
customblock: true
assembly: true🗡️ attribute — 属性后端
| 键 | 默认值 | 可选值 | 作用 |
|---|---|---|---|
attribute.backend | native | native / attributeplus / auto | native=QCL 自带原生属性，无需任何属性插件；attributeplus=交 AttributePlus；auto=有第三方则优先，否则回退 native |
全生态（QI/QS/QC/QSt/QF）统一从这里读后端。属性怎么用、怎么自定义 → 属性系统。
🛢️ database — 数据存储
QCL 为整个秦淮生态提供统一的数据存储。
| 键 | 默认值 | 可选值 | 作用 |
|---|---|---|---|
database.type | sqlite | sqlite、mysql | 选择存储后端 |
database.sqlite.data-folder | data | 任意目录名 | SQLite 数据文件夹（相对插件目录） |
database.mysql.host | localhost | 主机/IP | MySQL 地址 |
database.mysql.port | 3306 | 端口号 | MySQL 端口 |
database.mysql.database | qinhcorelib | 库名 | MySQL 数据库名 |
database.mysql.username | root | 用户名 | MySQL 账号 |
database.mysql.password | ""（空） | 密码字符串 | MySQL 密码 |
🧭 何时用哪个？
| 场景 | 推荐 |
|---|---|
| 单服、玩家不多、想省事 | sqlite（零配置、开箱即用） |
| 多服互通 / 大型服 / 需要外部读取数据 | mysql |
📁 SQLite 数据目录结构
当 type: sqlite 时，数据存放在 plugins/QinhCoreLib/data/（即 data-folder 指定的目录）：
plugins/QinhCoreLib/data/
├── global.db # 全局库（跨玩家的公共数据）
├── {uuid}.db # 每个玩家一个独立库，文件名是玩家 UUID
├── {uuid}.db
└── ...💡
global.db存全局数据，每个玩家有一个以其 UUID 命名的独立库文件。备份时把整个data/目录打包即可。
⚠️ 改动后须知
- 切换
type（sqlite ⇄ mysql）或修改 MySQL 连接参数：必须重启服务器。数据库连接在启动时建立，/qcl reload不会重连。 - 切换后数据不会自动迁移，两套后端是独立的。
🐛 debug — 调试输出
| 键 | 默认值 | 可选值 | 作用 |
|---|---|---|---|
debug.enabled | false | true/false | 是否打印调试日志 |
debug.prefix | [QinhCoreLib-Debug] | 任意字符串 | 调试日志前缀 |
排查问题时把 enabled 改为 true，控制台会输出更详细的内部日志，每行带 prefix 前缀方便过滤。
⚠️ 改动后须知
/qcl reload即可生效（重载会刷新 config）。
💰 economy — 经济对接
QCL 统一封装多个经济插件，子插件无需关心底层用的是哪个经济。
| 键 | 默认值 | 可选值 | 作用 |
|---|---|---|---|
economy.default-provider | auto | auto、vault、excellenteconomy/ee、playerpoints/pp | 默认经济提供者 |
economy.default-currency | money | EE 货币 id（如 money/silver/gold） | 默认货币 id |
🔄 default-provider 的 auto 逻辑
当设为 auto 时，QCL 按如下规则自动挑选：
- 指定了 currency（货币 id）时 → 优先用 ExcellentEconomy（EE）（因为只有 EE 支持多货币）。
- 没指定 currency 时 → 优先级为 Vault > EE > PlayerPoints，谁可用就用谁。
如果你只想锁定某一个经济插件，把 default-provider 直接写成 vault / ee / pp 即可。
💵 default-currency 何时有意义？
| 提供者 | 是否使用 default-currency |
|---|---|
| ExcellentEconomy（EE） | ✅ 使用，必须是有效的 EE 货币 id |
| Vault | ❌ 忽略（Vault 单货币） |
| PlayerPoints | ❌ 忽略 |
也就是说，default-currency 只在用 EE 时才有意义，决定默认操作哪种货币。
🔗 在 GUI 等地方写经济动作时，可以用更精确的格式覆盖默认值，例如
excellenteconomy:gold:50，详见 命令与权限 与开发文档 经济API。
⚠️ 改动后须知
/qcl reload即可生效（reload 会重载经济）。
📜 javascript — 脚本引擎
QCL 内置 JavaScript 脚本引擎，供子插件挂钩逻辑（如 QI 的合成校验）。
| 键 | 默认值 | 可选值 | 作用 |
|---|---|---|---|
javascript.enabled | true | true/false | 是否启用脚本引擎 |
javascript.default-function | main | 任意函数名 | 引用不带函数名时调用的默认函数 |
javascript.debug.print-stacktrace | false | true/false | 脚本报错时是否打印完整堆栈 |
🧩 脚本路径格式
脚本引用格式为：命名空间:相对路径.js[:函数名]
qinhitems:hooks/craft.js:check # 调用 qinhitems 命名空间下 hooks/craft.js 的 check 函数
qinhitems:hooks/craft.js # 不写函数名 → 调用 default-function（默认 main）default-function：当引用不带函数名时，调用的就是这个默认函数（默认main）。print-stacktrace：开发/排错时设true，脚本抛异常会打印完整 Java 堆栈，便于定位。
⚠️ 改动后须知
/qcl reload会重载脚本，多数改动可热重载；如关闭/开启enabled建议重启确保彻底。
🔗 脚本开发详见 脚本API。
🧱 modules — 模块开关
QCL 是模块化的，modules 段可以逐个禁用不需要的模块，默认全部 true。
各模块对应能力
| 模块名 | 能力 |
|---|---|
config | 配置加载（基础，建议保持开启） |
database | 数据存储（SQLite/MySQL） |
reflection | 反射工具 |
modelengine | ModelEngine 对接（模型实体） |
customcrops | CustomCrops 对接（作物） |
craftengine | CraftEngine 对接（自定义方块/物品） |
mythicmobs | MythicMobs 对接 |
neigeitems | NeigeItems 对接 |
mmoitems | MMOItems 对接 |
gui | 自定义 GUI 系统 |
action | 动作系统 |
pdc | PersistentDataContainer 数据存储 |
item | 物品系统（含统一物品源引用） |
hologram | 全息文字 |
scheduler | 调度器 |
condition | 条件系统 |
expression | 表达式求值 |
script | 脚本系统 |
economy | 经济对接 |
customblock | 自定义方块 |
assembly | 装配/组装 |
🔧 如何禁用模块
把对应键改成 false 即可，例如不需要 MythicMobs 对接：
yaml
modules:
mythicmobs: false⚠️ 禁用的副作用警告
- 依赖被禁模块的功能会失效。例如禁用
item后，统一物品源引用、GUI 物品引用、子插件的物品 API 都会受影响。 - 子插件（QI/QS/QF/QSt 等）可能依赖某些模块。除非确定用不到，否则不要随意禁用
config、database、item、action、script、economy等核心模块。 - 仅当你确定服务器没装对应外部插件时，关掉对应对接模块（如
modelengine、mythicmobs）是安全且能省资源的。 - 禁用某模块后，
/qcl status detail中该模块会显示「未启用」。
⚠️ 改动后须知
- 模块开关影响初始化流程，建议重启服务器让模块装载/卸载彻底干净。
📋 改动生效方式速查表
| 配置段 | reload 够吗？ | 说明 |
|---|---|---|
database（连接/类型） | ❌ 重启 | 连接在启动时建立 |
debug | ✅ reload | — |
economy | ✅ reload | reload 会重载经济 |
javascript | ✅ reload（大多） | 开关 enabled 建议重启 |
modules | ❌ 重启 | 影响模块装载 |