📥 安装与架构

环境要求

安装步骤

1. 将构建产物放入 Bukkit/Paper 的 plugins/。
2. 需要跨服聊天时，在 Velocity 端部署同版本插件。
3. 启动服务端，生成 config.yml、channels.yml、formats.yml 和 filters.yml。
4. 分配频道与格式权限，再执行 /achat reload。
5. 跨服环境使用两个子服测试 global 或 staff 频道。

模块结构

AdventureChat/
├── plugin/                   # 最终打包入口与插件描述
├── project/common/           # 频道、格式、过滤、命令规则模型
├── project/runtime-bukkit/   # 聊天管线、GUI展示、配置和命令
└── project/runtime-velocity/ # adventurechat:main 跨服转发桥

📡 频道系统

每个频道都由 channels.yml 中的独立节点定义。

默认频道

字段说明

配置示例

channels:
  trade:
    display: "&6Trade"
    permission: "adventurechat.channel.trade"
    format: "default"
    aliases: ["$" ]
    commands: ["trade"]
    range: -1
    default: false
    proxy: true
    disabled-functions: ["mentionall"]

🎨 消息格式

formats.yml 同时支持简单 pattern 与组件列表。拥有多个格式权限时，核心会选择第一个满足权限与条件的格式。

可用占位符

组件字段

• text — 当前组件文字
• hover — 多行悬浮说明
• suggest — 点击后填入命令
• click — 点击执行命令
• copy — 点击复制内容
• url — 打开网页
• condition / permission — 条件化显示

格式示例

formats:
  default:
    permission: "adventurechat.format.default"
    pattern: "{channel} &7{display}&f: {message}"
    components:
      - text: "&7{display}"
        hover:
          - "&7点击私聊 {player}"
        suggest: "/w {player} "
      - text: "&f: {message}"

✨ 交互功能

功能开关

展示记录

物品栏与末影箱展示会生成短期 ID，其他玩家可通过交互组件触发 /achat view <id> 查看；过期后返回“这个展示已经过期”。

🛡️ 内容过滤

本地规则

本地规则可替换敏感词，或将 replacement 设置为 BLOCK 直接阻断消息。

local:
  example-replace:
    word: "badword"
    replacement: "***"
    bypass-permission: "adventurechat.filter.bypass"
  example-block:
    word: "blockedword"
    replacement: "BLOCK"
    bypass-permission: "adventurechat.filter.bypass"

云词库

在 config.yml 开启 settings.cloud-filter.enabled，配置 URL 与刷新间隔。也可以执行 /achat cloudsync 立即同步。

🎛️ 命令控制器

命令控制器用于在玩家执行命令前检查匹配规则、权限、条件和冷却，并可将命令重定位为其他指令。

字段说明

command-controller:
  enabled: true
  rules:
    - pattern: "version|ver|plugins|pl"
      exact: false
      permission: "adventurechat.admin"
      cooldown: 3
      relocate: []
    - pattern: "rules"
      exact: true
      cooldown: 5
      relocate:
        - "say {player} is reading the rules."

🌐 Velocity 跨服桥接

工作方式

1. Bukkit 端将代理频道编码为插件消息。
2. Velocity 监听 adventurechat:main。
3. 消息被转发到除来源服之外的全部已注册子服。
4. 目标 Bukkit 端按频道权限筛选接收者并渲染组件。

代理端命令

检查清单

• Bukkit 与 Velocity 使用相同插件版本
• 需要跨服的频道设置 proxy: true
• 发送者与接收者均拥有频道权限
• 代理日志出现 Enabled v... on Velocity

⚙️ 配置文件

主配置示例

settings:
  cloud-filter:
    enabled: false
    url: "https://raw.githubusercontent.com/Yurinann/Filter-Thesaurus-Cloud/main/database.json"
    refresh-minutes: 30
  features:
    json-text: true
    kether: true
    hex-color: true
    mention: true
    show-item: true
    show-inventory: true
    show-enderchest: true
    show-image: false
permissions:
  admin: "adventurechat.admin"
  command: "adventurechat.command"
  reload: "adventurechat.command.reload"

⌨️ 命令与权限

Bukkit 命令

频道与格式权限

• adventurechat.channel.global
• adventurechat.channel.local
• adventurechat.channel.staff
• adventurechat.format.default
• adventurechat.format.local
• adventurechat.format.staff
• adventurechat.filter.bypass
• adventurechat.admin

🔗 插件联动

🧰 排错指南

频道消息没有发送

• 确认玩家拥有频道与格式权限
• 检查频道是否为 default，或消息是否使用了别名/频道命令
• 本地频道确认接收者在 range 范围内
• 检查 filters.yml 是否将消息阻断

跨服频道只有本服可见

• 检查 Velocity 端插件是否启动
• 确认频道 proxy: true
• 确认所有子服部署同版本 Bukkit 端

修改配置没有生效

执行 /achat reload 并检查返回的频道、屏蔽词和规则数量。若刚替换 JAR，请完整重启。

📝 版本说明

v1.0.0 当前

• NEW Paper/Spigot 聊天拦截管线
• NEW 多频道、多格式与独立权限
• NEW JSON 组件、HEX 颜色和提及功能
• NEW 本地/云敏感词过滤
• NEW 命令控制器与动态频道命令
• NEW Velocity 插件消息桥

规划中

• MiniMessage 与组件解析进一步完善
• 图片展示
• PacketEvents 高级显示桥