↓ 安装与兼容

安装步骤

1. 将 AdventureEffect-3.0.0-universal.jar 放入服务端 plugins/。
2. 按服务端核心要求选择 Java；26.1 及以上服务端使用 Java 25。
3. 重启服务端，等待插件生成默认配置。
4. 设置效果权限，玩家输入 /ae 打开 GUI。

游戏版本

插件使用 Java 17 字节码、Bukkit 1.20.1 公共 API 和 api-version: 1.20 构建，不依赖 NMS 或 CraftBukkit 版本包。

核心说明

• Spigot、Paper、Purpur：主要支持目标。
• Leaf：按其 Paper 插件兼容能力列为兼容目标，生产服部署前应在目标构建回归。
• DeerFoliaPlus / Folia：3.0.0 暂未正式支持。

从旧版本升级

1. 备份 plugins/AdventureEffect/ 和数据库。
2. 删除旧版本插件 JAR，只保留 3.0.0 Universal JAR。
3. 启动后插件会自动补充缺失的默认配置键。
4. 检查 GUI、权限、方块黑名单和声音范围，再开放生产流量。

› 命令列表

主命令

主命令别名：/ae、/adventureeffect、/aeffect。

授权类型

示例

/ae grant Steve kill lightning
/ae grant Steve attack flame_trail
/ae grant Steve sound bell_toll
/ae grant Steve break stone_button
/ae grant Steve place arrow_tick
/ae revoke Steve break stone_button
/ae reload

◆ 权限节点

权限表

LuckPerms 示例

lp group vip permission set adventureeffect.kill.lightning true
lp group vip permission set adventureeffect.attack.* true
lp group vip permission set adventureeffect.sound.* true
lp group vip permission set adventureeffect.block-break.* true
lp group vip permission set adventureeffect.block-place.* true

后五类权限前缀可以在 config.yml 的 permissions 中修改。GUI 选择和实际事件触发时都会检查权限；失去权限的旧选择会被自动清除。

▦ GUI 布局

主菜单

方块音效分类

选择菜单

选择菜单为 54 格，每页使用槽位 10-16、19-25、28-34、37-43，共显示 28 个项目。

• 69 个击败特效：3 页
• 40 个攻击特效：2 页
• 45 个击败音效：2 页
• 50 个方块音效：2 页

菜单标题、大小和槽位位于 menus/gui-layout.yml。无效大小或槽位会回退到安全默认值。

✦ 效果库

定义文件

击败特效示例

kill-effects:
  my_custom_effect:
    name: "&a自定义特效"
    description:
      - "&7在死亡位置产生火焰粒子"
    icon: DIAMOND
    icon-glow: true
    particles:
      - type: FLAME
        count: 30
        offset-x: 0.5
        offset-y: 1.0
        offset-z: 0.5
        speed: 0.05
    lightning-strike: false
    sound: ENTITY_ENDER_DRAGON_GROWL
    sound-volume: 1.0
    sound-pitch: 1.0

攻击特效示例

attack-effects:
  my_attack:
    name: "&c自定义攻击"
    description: ["&7自定义攻击粒子"]
    icon: BLAZE_POWDER
    particle-type: FLAME
    particle-count: 8
    offset-x: 0.3
    offset-y: 0.5
    offset-z: 0.3

击败音效示例

kill-sounds:
  my_custom_sound:
    name: "&e自定义音效"
    description: ["&7短促音效"]
    icon: NOTE_BLOCK
    sound: BLOCK_NOTE_BLOCK_PLING
    volume: 1.0
    pitch-low: 0.5
    pitch-mid: 1.0
    pitch-high: 2.0

♫ 方块短音效

音效库

破坏和放置共用 50 个定义，但玩家选择、权限和冷却类型互相独立。默认包含 30 个 Note Block 音符和 20 个短促交互音。

触发过滤

settings:
  action-sound-cooldown: 2
  action-sound-ignore-creative: true
  action-sound-block-blacklist:
    - BEDROCK
    - BARRIER
    - COMMAND_BLOCK
    - CHAIN_COMMAND_BLOCK
    - REPEATING_COMMAND_BLOCK
    - STRUCTURE_BLOCK
    - JIGSAW
    - LIGHT

黑名单接受 Bukkit Material 名称，不区分大小写，也兼容 minecraft:stone。被其他插件取消的事件不会播放声音。

个人与附近模式

settings:
  action-sound-playback:
    block-break:
      mode: PERSONAL
      radius: 16.0
    block-place:
      mode: NEARBY
      radius: 12.0

radius 仅在 NEARBY 下生效，有效范围为 1-64 格，越界值会自动限制。附近模式使用球形实际距离，并保证操作者本人能听到。

§ Lore 物品效果

工作方式

ae/lore-effects.yml 根据物品材质与 Lore 关键词绑定已有的击败、攻击或击败音效。比较时会移除颜色代码并使用包含匹配。

• 主手优先，副手补充主手没有提供的效果类型
• Lore 效果优先于玩家的全局选择
• 未被 Lore 覆盖的类型继续使用全局选择
• 玩家可在物品效果 GUI 中独立开关三类 Lore 效果并调节 Lore 音量

配置示例

lore-effects:
  DIAMOND_SWORD:
    - lore: "击败效果-雷电"
      kill-type: lightning
    - lore: "攻击效果-火焰"
      attack-type: flame_trail
    - lore: "雷霆之怒"
      kill-type: lightning
      attack-type: electric_shock
      sound-type: explosion_pop

手持匹配物品时输入 /ae，插件会显示全局设置与物品效果设置入口。没有匹配规则时直接进入主菜单。

⚙ 配置文件

运行目录

plugins/AdventureEffect/
├── config.yml
├── messages.yml
├── playerdata.yml
├── .license-cache.yml
├── ae/
│   ├── effects-kill.yml
│   ├── effects-attack.yml
│   ├── effects-sound.yml
│   ├── action-sounds.yml
│   └── lore-effects.yml
└── menus/
    └── gui-layout.yml

主配置职责

消息前缀

默认前缀为 &f[&f&l!&f]。插件只迁移曾经提供的旧默认值，不会覆盖管理员自行设置的前缀。

重载边界

/ae reload 会重载主配置、消息、效果库、GUI、玩家数据和许可证状态。MySQL、Redis、sync.enabled 或 sync.server-id 变更后必须重启，因为该命令不会重建网络连接。

⇄ 保存与跨服同步

本地模式

默认使用 playerdata.yml，保存击败、攻击、击败音效、声调、Lore 开关与音量，以及破坏和放置方块音效选择。

跨服模式

• MySQL 保存最终玩家数据
• Redis Hash 提供缓存
• Redis Pub/Sub 通知其他子服刷新
• Redis 未命中时回源 MySQL
• 每个子服必须配置不同的 sync.server-id

sync:
  enabled: false
  server-id: "survival-1"
  mysql:
    host: "localhost"
    port: 3306
    database: "adventureeffect"
    username: "root"
    password: ""
    table-prefix: "ae_"
  redis:
    host: "localhost"
    port: 6379
    password: ""
    database: 0
    key-prefix: "ae:"

# PlaceholderAPI

占位符

未选择时返回“无”。安装 PlaceholderAPI 后，插件会在启动时自动挂接扩展。

i 运维与统计

管理员上线推送

拥有 adventureeffect.admin 的玩家上线后，默认收到版本号、本次更新、赞助者、作者 QQ 和网站 Wiki。可在 admin-notice 中编辑或关闭，{version} 会替换为实际插件版本。

bStats

插件已集成 bStats Bukkit Metrics 3.2.1，项目 ID 为 30987。服务器管理员可在 plugins/bStats/config.yml 中全局关闭统计。

查看 AdventureEffect bStats

许可证

license.enforce: false 时只记录验证状态，不限制功能。付费发行时填写验证地址和密钥并启用强制模式。强制模式仅在在线验证有效或已验证缓存处于宽限期时允许打开 GUI 和播放效果。

兼容测试

mvn test
.\scripts\api-compatibility.ps1
.\scripts\compatibility-matrix.ps1

当前快速测试共 40 项。Docker 脚本默认覆盖 8 个关键 Paper 边界版本，-Mode All 可尝试全部 22 个目标版本，并检查插件启用、链接错误、ae list 和 ae reload。

? 常见问题

效果不生效

1. 确认玩家拥有对应权限。
2. 使用 /ae list 检查 ID 是否加载。
3. 确认玩家已在 GUI 选择效果。
4. 击败特效仅在玩家击杀玩家时触发。

修改配置后没有变化

执行 /ae reload。同步连接参数变更后重启服务器。

方块音效没有触发

检查创造模式过滤、材质黑名单、冷却、玩家选择和权限。若方块事件已被领地或保护插件取消，本插件不会播放声音。

附近模式会全服播放吗

不会。插件只向同世界、方块中心指定球形半径内的玩家发送声音。

为什么不直接支持 DeerFoliaPlus

DeerFoliaPlus 使用 Folia 区域线程模型。支持它需要重构调度器和跨区域实体访问，并完成真实服压力测试；只添加支持声明存在数据竞争风险。

如何备份玩家数据

单服备份 playerdata.yml；跨服模式同时备份 MySQL 表。升级前建议备份整个插件目录。

+ 更新日志

3.0.0

• 新增 破坏和放置音效可独立选择 PERSONAL 或 NEARBY
• 新增 附近模式 1-64 格半径限制
• 更新 Wiki、bStats、Leaf 与 DeerFoliaPlus 支持边界
• 版本 单一 Universal JAR 支持 1.20.x、1.21.x 和 26.x

2.4.1

• 新增 JUnit、MockBukkit、最低/最高 API 与 Docker 兼容测试脚本。

2.4.0

• 改为单一 Universal JAR，加入 22 个目标版本识别。

2.3.1

• 新增创造模式过滤和方块材质黑名单。

2.3.0

• 取消跳跃和 Shift 音效。
• 击败特效、击败音效和方块短音效各扩充 20 项。
• 默认消息前缀改为 &f[&f&l!&f]。