跳到主要内容

快速开始

本文档将帮助你快速安装和配置 Baikiruto 插件。

安装​

前置要求​

  • Minecraft 服务端：Bukkit/Spigot/Paper 1.12 - 26.1.1
  • Java 版本：Java 21+
  • TabooLib：6.2.4+

下载插件​

  1. 访问 GitHub Releases 下载最新版本
  2. 或者克隆仓库自行编译： 
    git clone https://github.com/YsGqHY/Baikiruto.git
    cd Baikiruto
    ./gradlew build

安装步骤​

  1. 将 Baikiruto-x.x.x.jar 放入服务器的 plugins/ 目录
  2. 确保 TabooLib 已安装（如果没有，插件会自动下载）
  3. 重启服务器
  4. 插件会自动生成 config.yml、items/example.yml 和 display/def.yml
  5. 当前发行包不包含 items/blackbox/*.yml 测试示例；如果你在源码仓库或测试计划里看到这些文件名，请把它们视为内部测试资源而不是默认释放内容

目录结构​

插件安装后会在 plugins/Baikiruto/ 目录下生成以下文件：

Baikiruto/
├── config.yml          # 主配置文件
├── data.db             # SQLite 数据库（默认）
├── display/            # 显示模板目录
│   └── def.yml         # 默认显示模板
└── items/              # 物品配置目录
    └── example.yml     # 示例物品配置

display/ 目录存放显示模板，用于定义物品名称和 Lore 的格式化模板。def.yml 是插件自带的默认模板，首次启动时自动释放。items/ 和 display/ 下的 .yml 文件都会被递归扫描，所以你后续可以按功能自己继续拆子目录。

按当前发行包实际内容，默认示例资源只有：

  • config.yml
  • items/example.yml
  • display/def.yml

items/blackbox/ 相关文件名只在源码测试计划和内部校验场景里出现，不属于当前面向服主发放的默认示例集。

主配置文件​

config.yml 是插件的主配置文件，包含以下配置项：

settings:
  # 调试模式开关
  debug: false

  # 调试白名单（玩家名称）
  debug-users:
    - "Y_Mical"
    - "TabooLib"

  mini-message:
    # 启用后可在名称 / Lore 中保留并渲染 <red> 这类 MiniMessage 标签
    enabled: false

script:
  preheat:
    # 脚本预热开关
    enabled: true

    # 预热策略：ON_ENABLE（启动时）/ ON_DEMAND（按需）
    strategy: "ON_ENABLE"

    # 批量编译数量（推荐 1-256）
    batch-size: 64

operations:
  watcher:
    # 文件监听器开关
    enabled: true

    # 防抖延迟（tick）
    debounce-ticks: 20

  reload-online-update:
    # 重载后自动更新在线玩家物品
    enabled: true

  async-tick:
    # 启用 ASYNC_TICK 周期扫描
    enabled: true

    # 全局默认触发间隔（tick）
    # 单个物品可通过 meta.async-tick.interval 覆盖
    default-interval: 100

  performance-log:
    # 性能日志开关
    enabled: true

    # 慢构建阈值（毫秒）
    slow-build-millis: 10

  hook:
    mythic:
      # MythicMobs 集成
      enabled: true
    attribute-plus:
      # AttributePlus 集成
      enabled: true
    head-database:
      # HeadDatabase 集成
      enabled: true

database:
  # MySQL 开关（false = 使用 SQLite）
  enabled: false

  # MySQL 连接配置
  host: "localhost"
  port: 3306
  user: "root"
  password: "root"
  database: "minecraft"

  # 数据表名（空 = 自动生成）
  table: ""

  # 玩家数据键模式（true = 玩家名，false = UUID）
  username-mode: false

  # SQLite 文件路径
  sqlite-file: "data.db"

配置说明​

调试模式​

  • debug: true - 开启后会输出详细的生命周期和运行时诊断信息
  • debug-users - 调试白名单，只有列表中的玩家会收到调试信息

MiniMessage 文本​

  • mini-message.enabled: true - 允许在名称和 Lore 中保留 <red>、<gradient:...> 这类 MiniMessage 标签
  • 这个开关只有在运行环境实际提供 MiniMessage 类时才会生效
  • 如果服务端环境不支持，Baikiruto 会保留原配置文本并输出提示日志，因此生产服建议先用一把测试物品确认显示效果

脚本预热​

  • enabled: true - 启动时批量编译所有脚本，减少运行时开销
  • strategy: "ON_ENABLE" - 启动时预热（推荐）
  • batch-size: 64 - 每批编译的脚本数量，建议 1-256

文件监听器​

  • enabled: true - 监听 items/ 目录变化，自动增量重载
  • debounce-ticks: 20 - 防抖延迟，避免频繁重载

在线更新​

  • reload-online-update: true - 重载后自动检查并更新在线玩家背包中的物品

异步轮询​

  • operations.async-tick.enabled: true - 启用 on_async_tick 的周期扫描；如果你完全不用这类脚本，可以全局关闭
  • operations.async-tick.default-interval: 100 - 全局默认间隔（tick）；单个物品可在 meta.async-tick.interval / ticks / period 里覆盖
  • 真实执行策略是“持续扫描 + 按物品分散触发”：只有写了 on_async_tick 且满足条件的 Baikiruto 物品才会真正执行脚本，不会把所有物品都堆到同一 tick

性能日志​

  • enabled: true - 定期输出性能和缓存指标
  • slow-build-millis: 10 - 单个物品构建超过此阈值时发出警告

插件集成​

  • operations.hook.mythic.enabled: true - 启用 MythicMobs 集成
  • operations.hook.attribute-plus.enabled: true - 启用 AttributePlus 属性同步
  • operations.hook.head-database.enabled: true - 启用 HeadDatabase 头颅转换
  • PlaceholderAPI 没有独立开关，显示阶段拿得到玩家上下文时会自动尝试替换 PAPI 变量

如果你要看每个 Hook 的完整写法、联动示例和排错方式，请直接查看 Hook 联动。

数据库配置​

  • enabled: false - 默认使用 SQLite，设为 true 启用 MySQL
  • username-mode: false - 使用 UUID 作为玩家数据键（推荐）

快速测试​

安装完成后，你可以通过以下命令测试插件是否正常工作：

# 查看所有物品
/baikiruto list

# 给自己发放示例物品
/baikiruto give example:all_features

# 打开物品菜单
/baikiruto menu

# 查看插件状态
/baikiruto selfcheck

下一步​

常见问题​

插件无法加载​

  • 检查 Java 版本是否为 Java 21+
  • 检查 TabooLib 是否已安装
  • 查看控制台错误信息

物品无法发放​

  • 使用 /baikiruto list 检查物品是否已注册
  • 使用 /baikiruto selfcheck 检查插件状态
  • 开启 debug: true 查看详细日志

脚本不生效​

  • 检查脚本语法是否正确（Fluxon 语法）
  • 开启 debug: true 查看脚本执行日志
  • 确认脚本预热已启用

获取帮助​

支持开源

如果 Baikiruto 帮助到了你，请到 GitHub 仓库 点个 Star ⭐