📥 安装与依赖

环境要求

安装步骤

1. 将 AdventureRule.jar 放入 plugins/
2. 重启服务器，生成默认配置
3. 编辑 config.yml，按需配置档位、效果、限制和数据存储
4. 按运行版本编辑 rules-book 或 rules-dialog 下的规则文件
5. 执行 /ar reload

文件结构

plugins/AdventureRule/
├── config.yml          # 主配置
├── messages.yml        # 消息配置
├── dialogs.yml         # 自定义 Dialog 配置
├── rules-book/         # 低版本规则书配置，不包含 Dialog 节点
│   ├── server_rule/
│   │   └── rule.yml
│   └── refuse_book/
│       └── rule.yml
├── rules-dialog/       # 高版本 Dialog 配置，不包含书本 pages
│   ├── server_rule/
│   │   └── rule.yml
│   └── refuse_book/
│       └── rule.yml
└── data/               # 玩家同意数据

📖 规则系统

工作原理

1. 新玩家加入、配置阶段连接、或规则过期后重新加入时触发规则检查
2. 低版本档位打开规则书；高版本档位打开原生 Dialog
3. 玩家点击同意按钮后写入同意记录
4. 同意后解除所有行为限制和视觉效果

多规则支持

支持配置多个规则 ID，每个规则有独立的规则书内容和过期策略。玩家需要全部同意才能正常游戏。

低版本规则书配置

rules-book/规则ID/rule.yml 只包含书本页面 pages，不包含 Dialog 配置。

title: "服务器规则"
author: "Server Admin"
pages:
  - |
    &0&l欢迎来到服务器！

    [&a&l我已阅读并同意](command:ar:consent)
    [&c&l不同意](command:ar:deny)
buttons:
  consent:
    text: "我已阅读并同意"
    command: "ar:consent"
  deny:
    text: "不同意"
    command: "ar:deny"
    deny-book: "refuse_book"

高版本 Dialog 规则配置

rules-dialog/规则ID/rule.yml 只包含 Dialog 内容，不包含书本 pages。

dialog:
  title: "&6&l服务器规则确认"
  can-close-with-escape: false
  button-width: 150
  body:
    - |
      &f欢迎来到服务器。
      &7请阅读并确认服务器规则。
  buttons:
    - consent
    - deny

🪟 高版本 Dialog

启用条件

Dialog 档位要求服务端支持 Paper Dialog API。默认自动条件为 Minecraft 1.21.7+ 且 Java ≥ dialog-min-java。

settings:
  presentation:
    mode: auto
    dialog-min-java: 25
    trigger-stage: auto
    configure-timeout-seconds: 90
    configure-timeout-action: disconnect

触发阶段

自定义 Dialog

dialogs.yml 用于配置任意可由指令弹出的 Dialog。每个 Dialog 目前为确认型界面，显示两个按钮。

dialogs:
  example_menu:
    title: "&6&l服务器导航"
    can-close-with-escape: true
    button-width: 150
    body:
      - |
        &f请选择接下来的操作。
    buttons:
      survival:
        text: "&a进入生存服"
        tooltip: "&7点击后执行跳服命令"
        action: transfer
        server: "survival"
      leave:
        text: "&c断开连接"
        action: disconnect
        message: "&c你已主动离开服务器。"

按钮动作

弹出指令

/ar dialog Steve example_menu

✨ 视觉效果

药水效果

未同意规则的玩家会被施加药水效果作为视觉提示：

effects:
  enabled: true
  potion-effects:
    - type: BLINDNESS
      amplifier: 0
      duration: 999999      # 极长时间 (同意后移除)
    - type: SLOWNESS
      amplifier: 255         # 极高等级 = 无法移动
      duration: 999999

提醒消息

reminder:
  enabled: true
  interval-ticks: 100       # 提醒间隔 (tick)
  title:
    enabled: true
    title: "&c请先阅读服务器规则"
    subtitle: "&7输入 /rule 打开规则书"
  sound:
    enabled: true
    sound: ENTITY_EXPERIENCE_ORB_PICKUP
    volume: 1.0
    pitch: 1.0

🚫 行为限制

限制配置

未同意规则的玩家以下行为将被完全禁止：

restrictions:
  block-move: true           # 禁止移动
  block-chat: true           # 禁止聊天
  block-command: true        # 禁止执行命令
  block-interact: true       # 禁止交互
  block-attack: true         # 禁止攻击
  block-break: true          # 禁止破坏方块
  block-place: true          # 禁止放置方块
  block-drop: true           # 禁止丢弃物品
  block-pickup: true         # 禁止拾取物品
  allowed-commands:          # 白名单命令 (即使block-command=true)
    - "/rule"
    - "/login"
    - "/register"
    - "/l"

🔑 AuthMe / 铁砧登录兼容

工作原理

当服务器安装了 AuthMe 登录插件时，AdventureRule 会等待玩家完成 登录或注册 后再触发规则书检查，避免与登录流程冲突。

AuthMe 模式

监听 AuthMe 的 LoginEvent 和 RegisterEvent，玩家登录或注册成功后延迟触发规则书。内置去重机制防止注册自动登录时重复触发。

AuthMeAnvilLogin (铁砧登录) 兼容 v1.2.0

AuthMeAnvilLogin 是一个使用铁砧界面作为登录注册 UI 的插件。它通过 AuthMe API 的 forceLogin() / forceRegister() 完成认证，会自动触发 AuthMe 事件。

AdventureRule 自动检测 AuthMeAnvilLogin 插件：

• 检测到 AuthMeAnvilLogin 时，即使 authme.enabled: false，也会自动启用 AuthMe 挂钩模式
• 玩家在铁砧 GUI 中完成登录/注册后，自动弹出规则书
• 建议将 delay-after-login 设为 40-60，等待铁砧 GUI 完全关闭

配置

# config.yml
settings:
  authme:
    # 手动启用 AuthMe 挂钩 (检测到 AuthMeAnvilLogin 时自动启用)
    enabled: false
    # 登录/注册成功后延迟触发 (tick)
    # 使用 AuthMeAnvilLogin 时建议 40-60
    delay-after-login: 40

流程图

玩家加入服务器
  └─ AuthMeAnvilLogin 打开铁砧 GUI
      └─ 玩家输入密码 → 登录/注册成功
          └─ AuthMe 触发 LoginEvent / RegisterEvent
              └─ AdventureRule 监听到事件
                  └─ 延迟 40 tick 后弹出规则书

🏠 出生点配置

概览

可配置未同意规则的玩家强制传送到指定出生点，防止玩家在受限状态下走失。

配置

spawn:
  enabled: false
  world: "world"
  x: 0.0
  y: 64.0
  z: 0.0
  yaw: 0.0
  pitch: 0.0
  teleport-on-join: true      # 未同意时每次登录传送

🛡️ 虚空保护

概览

未同意规则的玩家掉入虚空时，自动传送回出生点，防止死亡循环。

配置

void-protection:
  enabled: true
  min-y: -64                  # 低于此 Y 坐标触发保护

⚙️ config.yml 完整配置

完整参考

# AdventureRule v1.8.0 主配置（节选）
settings:
  check-interval: 60
  default-expire-days: 7
  debug: false
  metrics:
    bstats-id: 31164
  trigger-delay: 40

  effects:
    blindness:
      enabled: true
      duration: 6000
      amplifier: 1
    slowness:
      enabled: true
      duration: 6000
      amplifier: 1

  restrictions:
    allow-left-click: false
    allow-right-click: false
    allow-movement: false
    allow-npc-interact: false
    block-all-commands: true
    allowed-commands:
      - "/login"
      - "/register"
      - "/l"
      - "/reg"
    block-chat: true
    block-item-drop: true
    block-item-pickup: true

  presentation:
    mode: auto
    dialog-min-java: 25
    trigger-stage: auto
    configure-timeout-seconds: 90
    configure-timeout-action: disconnect

  reminder:
    enabled: true
    interval: 30
    message: "&e[系统] &f请阅读并同意本次协议 -> "
    click-text: "&a&l[点我打开]"
    click-command: "/rule"
    hover-text: "&e点击打开规则"

database:
  type: yaml
  host: localhost
  port: 3306
  database: adventurerule
  username: root
  password: ""
  table-prefix: "ar_"

reload-recheck:
  enabled: true
  worlds: []

💬 消息配置

消息文件

命令提示、帮助文本、reload 反馈等在 messages.yml 中配置，支持颜色代码和变量：

# messages.yml (部分)
prefix: "&6[AdventureRule]&r "
commands:
  no-permission: "&c你没有权限执行此命令。"
  usage-dialog: "&c用法: /ar dialog <玩家> <DialogID>"
  dialog-open-success: "&a已向玩家 %player% 打开 Dialog '%dialog%'。"
help:
  dialog: "&e/ar dialog <玩家> <DialogID> &7- 对玩家弹出自定义 Dialog"
reload:
  local-recheck: "&b[复检] 单服扫描完成：对 %count% 个在线玩家弹出未同意的规则。"

🗄️ 数据库

存储类型

database:
  type: yaml                # yaml / mysql
  host: localhost
  port: 3306
  database: adventurerule
  username: root
  password: ""
  table-prefix: "ar_"

数据清理

expiry-task:
  interval-minutes: 30      # 定时清理过期记录

⌨️ 命令列表

玩家命令

管理员命令

使用示例

# 对玩家触发默认规则
/ar trigger Steve

# 对玩家触发指定规则
/ar trigger Steve privacy_policy

# 查看玩家是否已同意所有规则
/ar check Steve

# 重置玩家的某个规则（要求重新同意）
/ar reset Steve default

# 重置玩家所有规则
/ar reset Steve

# 弹出自定义 Dialog
/ar dialog Steve example_menu

🔐 权限节点

📝 更新日志

v1.8.0 LATEST

• NEW 自定义 Dialog — 新增 dialogs.yml 与 /ar dialog <玩家> <DialogID>
• NEW 按钮动作 — 支持 command、transfer、disconnect、rule、close
• CONFIG 断开提示 — Rule 按钮可配置 disconnect-message

v1.7.0

• NEW 双档位规则目录 — rules-book 与 rules-dialog 按运行环境自动选择
• NEW 配置阶段 Dialog — 高版本可在玩家进入世界前显示规则 Dialog
• CONFIG messages.yml — 命令提示、帮助、reload 反馈外部化

v1.3.0

• NEW 消息外部化 — 所有文本移至 messages.yml

v1.2.0

• NEW AuthMeAnvilLogin 铁砧登录兼容 — 自动检测插件，铁砧登录/注册后弹出规则书
• NEW AuthMe 注册事件 — 同时监听 LoginEvent + RegisterEvent，内置去重机制
• IMPROVED 自动挂钩 — 检测到 AuthMeAnvilLogin 时自动启用 AuthMe 模式，无需手动配置
• CONFIG delay-after-login — 默认值调整为 40 tick，适配铁砧 GUI

v1.1.5

• IMPROVED 虚空保护 — 可自定义触发 Y 坐标
• IMPROVED 过期清理 — 定时任务自动清理过期记录
• CONFIG softdepend — 新增 AdventureManage

v1.1.0

• NEW 多规则支持 — 可配置多个独立规则 ID
• NEW 过期重签 — 规则同意可设有效期
• NEW MySQL 支持 — 跨服数据共享

v1.0.0

• NEW 初始版本 — 规则书、行为限制、视觉效果、AuthMe 兼容