主配置

主配置位于 plugins/Invero/config.yml。修改后完整重启服务端；/invero menu reload 只更新菜单，/invero gnode reload 只更新节点文件，都不会重读主配置。

以下“省略行为”指已有 config.yml 中确实没有该字段时的回退，不等于首次生成的随附配置。字段大小写按本文填写；这些主配置字段没有另一组别名。菜单窗口与图标字段写在各自的菜单文件中，见配置字段索引。

常用设置Copy Anchor Link

随附值与省略值Copy Anchor Link

随附配置主动填写了工作路径，因此正常首次启动能加载示例；删除路径字段不等于“恢复默认目录”。菜单文件筛选还有一处差别：删除 Workspaces.filter 后，TOML 不再被匹配。Paste 删除服务类型则会从随附选择的 lucko 改为 pastegg。

工作空间与文件筛选Copy Anchor Link

Workspaces:
  file-listener: true
  filter: '^(?![#!]).*\.(?i)(conf|hocon|yaml|yml|toml|json)$'
  paths:
    - 'plugins/Invero/workspace'

上面是随附值。paths 相对服务端运行目录，逐个填写，可使用多个目录，不会自动相对于 plugins/Invero 补全。菜单递归扫描子目录，以 # 或 ! 开头的文件名被这条规则排除，但同名风格的目录不被整体排除。

每个文件只定义一个菜单，顶层需有 menu 或 title；仅含 nodes 的文件不会作为菜单加载。省略 Workspaces.paths 会得到空路径列表，不会自动使用 workspace。

只加载 YAML 菜单时，把同一节点改成：

Workspaces:
  filter: '^(?![#!]).*\.(?i)(yaml|yml)$'

过滤规则只决定是否读取，不会转换文件内容。扩展名对应的格式见下表。

文件监听只挂到成功加载的菜单原文件。新增、改名、移动或删除后执行 /invero menu reload；关闭监听时所有菜单修改都需要这条命令。

目录与示例文件Copy Anchor Link

workspace 与 global-nodes 是独立的加载入口，不是放在插件目录里的所有 YAML 都会读取。目录不存在时，会释放相应的随附文件；已有目录不会因为缺少某个示例就自动补齐。

多个不存在的菜单目录会各自释放同一套示例，可能产生重复菜单 ID。菜单示例中附带的 global-nodes 子目录不会自动加入全局节点路径，仍需在 GlobalNodes.paths 中指定。

扩展名与格式Copy Anchor Link

筛选允许某个文件名，不代表文件内容按你预想的格式解析：

扩展名的格式识别区分大小写；随附正则虽然允许大写扩展名，识别失败时仍会按 YAML 回退。使用上表的小写扩展名可避免筛选与格式识别不一致。

HOCON 包含文件Copy Anchor Link

.conf 可以包含同目录的公共片段。例如在菜单 .conf 中单独写一行：

include "#shared.conf"

#shared.conf 不会被随附文件筛选单独加载成菜单，但仍可通过包含读取。Invero 会为这种包含写法补入当前菜单文件的父目录；include file("#shared.conf")、include required("#shared.conf")、include required(file("#shared.conf")) 也会经过补写。被包含文件的修改不属于菜单原文件的自动监听范围，修改后执行 /invero menu reload。

补写不是任意路径的自动定位：以 http 开头、含冒号或目录分隔符总数超过两个的路径不会被改写；其余匹配到的路径会加上当前父目录。需要关闭补写时，将下面这一行放在该 .conf 文件的最开头：

// IGNORE_HOCON_PATCH

关闭后由原解析器处理包含路径。补写还会把上面的 required 形式改成普通文件包含，不能依靠它保证“片段不存在时必报错”；被包含文件里的下一层包含也不保证得到同样的路径补写。

全局节点Copy Anchor Link

GlobalNodes:
  enabled: true
  paths:
    - 'plugins/Invero/global-nodes'
  filter: '^(?![#!]).*\.(?i)(conf|hocon|yaml|yml|toml|json)$'
  priority: menu-first

路径和规则同样是显式配置。与菜单不同，全局节点不递归子目录、没有自动文件监听。文件直接放在列出的目录内，顶层使用 nodes，保存后执行 /invero gnode reload。

enabled: false 时只查本地节点。具体保存与调用方式见全局节点。

全局节点的文件筛选Copy Anchor Link

GlobalNodes.filter 独立于 Workspaces.filter。全局节点文件直接放在 GlobalNodes.paths 指定的目录中，顶层使用 nodes；节点名来自 nodes 下的键，与文件名无关。例如：

nodes:
  server_label:
    type: CONST
    value: '生存服'

全局文件的节点条目要写成对象，不能把菜单本地节点的文字简写直接搬来。节点名区分大小写；重复节点名会被后读取的定义覆盖，不提供稳定的覆盖顺序。

执行 /invero gnode reload 会先清空再加载。若文件或某个节点出错，该节点不会自动保留旧定义；首次启动的节点错误可能不显示详细信息，手动重载可查看具体失败项。用 /invero gnode list 确认结果、/invero gnode test <节点名> 查看已加载内容。调用与查找顺序见节点。

文本与窗口默认值Copy Anchor Link

Kether:
  auto-placeholder-translate: true
Menu:
  virtual-by-default: false
  enable-raw-title-in-vanilla-inventory: false

auto-placeholder-translate 控制 Invero 对 minimessage / mmessage / mmsg、fluentmessage / fmessage / fmsg、broadcast / bc 消息语句的扩展注册，不是全站文本或 PlaceholderAPI 的总开关。不要用它代替安装 PAPI 扩展，也不要把关闭后仍存在的基础 broadcast 当成 Invero 增强广播。

virtual-by-default 只为未填写 menu.virtual 的菜单提供默认值，不强制覆盖单个菜单。涉及真实物品放入和取出的菜单按窗口设置与交互面板配置，不能仅凭标题效果更换窗口模式。

原始标题开关会尝试把普通窗口标题作为组件写入，但这个开关本身不能可靠地启用配套的原始标题解析，可能直接显示 JSON 原文；遇到这种情况保持 false 并使用普通标题。它不负责隐藏背包或切换虚拟模式。

配置中存在但不生效的字段Copy Anchor Link

颜色写法见颜色代码。

数据库Copy Anchor Link

SQLiteCopy Anchor Link

Database:
  type: SQLITE

数据保存在 plugins/Invero/data/invero_data.db。Database.sql 下的连接字段、表名不会用于 SQLite。保存和读取数据见持久数据。

SQLCopy Anchor Link

以下均为需要替换的连接示例占位值，不是可直接连接的账户：

Database:
  type: SQL
  sql:
    host: 'YOUR_DB_HOST'
    port: 3306
    user: 'YOUR_DB_USER'
    password: 'YOUR_DB_PASSWORD'
    database: 'YOUR_DATABASE'
    table: 'YOUR_TABLE_NAME'

字段写在 Database.sql 下，只在选择 SQL 时读取。

SQL 使用 MySQL 连接，不是通用 JDBC 地址入口；不支持通过这些字段填写任意驱动、SSL 参数或连接池选项。MONGODB 没有实现，写入它会按无法识别的类型回退为 SQLite，而不是连接 MongoDB。

更换存储类型、数据库或表名不会自动搬迁旧数据。修改后重启，检查后台的数据库连接结果；选择 SQL 却缺少整个 sql 节点会连接失败，不会在这种情况下自动改连 SQLite。

数据库连接池文件Copy Anchor Link

数据库运行库还会生成 plugins/Invero/datasource.yml。这是单独的连接池配置，不是 config.yml 中的 Database.sql 子节点；修改同样需要完整重启。下面字段都写在该文件的 DefaultSettings 下，没有别名。

这些驱动属性只在 DefaultSettings.DataSourceProperty 存在时逐项传入，不把随附示例当成无法省略的字段：

数据库地址、用户名、密码与目标表仍填写在 config.yml；不要将整段连接信息移到连接池文件。

内容导出服务Copy Anchor Link

menu dump、gnode dump、item encode、item encodePrint 都会将导出内容上传到所选服务。只有服务端需要访问该 HTTP API，不要求玩家客户端连接数据库或下载导出插件。

这三种服务只读取各自命名下的设置。省略整个 Paste 节点时，启动会补写一组内置服务配置，并选择 pastegg；补写内容不等于你自己的 Pastebin 账户配置，使用 Pastebin 时仍需主动替换密钥。

随附选择的 lucko 可以明确写成：

Paste:
  service-type: lucko
  services:
    lucko:
      base-url: 'https://api.pastes.dev'

另外两种配置：

Paste:
  service-type: pastegg
  services:
    pastegg:
      base-url: 'https://api.paste.gg/v1'

base-url 填服务 API，不填某一份粘贴内容的网页地址。地址可以改，但生成的 lucko、pastegg 查看链接仍使用它们各自的公开域名，不能仅靠替换 API 就实现任意私有粘贴站。

lucko 与 Pastebin 只上传第一份内容，pastegg 支持同次上传多份；物品 Base64 的取得方式与有效期差异见导出命令。不存在 Paste 独立重载命令，修改后重启服务端。