📥 安装教程

环境要求

安装步骤

1. 根据服务器版本下载对应 JAR
2. 将 JAR 放入 plugins/ 目录
3. 启动服务器 — 首次启动自动生成所有默认配置
4. 按需编辑配置后 /ae reload 热重载
5. 用 LuckPerms 或 /ae grant / /aep grant 授予玩家权限

配置文件结构

plugins/AdventureEffect/
├── config.yml                # 主配置 (设置、GUI布局、权限前缀、跨服同步)
├── messages.yml              # 所有消息文本 (GUI标题、按钮、提示)
├── ae/                       # AE 击败/攻击特效
│   ├── effects-kill.yml      # 50个击败特效
│   ├── effects-attack.yml    # 40个攻击特效
│   ├── effects-sound.yml     # 25个击败音效
│   └── lore-effects.yml      # Lore 物品效果规则
├── aep/                      # AEP 粒子效果
│   └── particles.yml         # 粒子效果定义 (模板式自动组合)
└── playerdata.yml            # 玩家数据 (自动生成，勿手动编辑)

⌨️ 命令列表

特效命令 /ae

别名: /adventureeffect、/aeffect

粒子命令 /aep

别名: /adventureparticle、/aparticle

🔐 权限节点

基础权限

效果权限

🖥️ GUI 使用

特效 GUI (/ae)

主菜单

3行界面，包含三个分类入口:

• 击败特效 (槽位11) — 50个击杀时播放的视觉效果
• 攻击特效 (槽位13) — 40个攻击时播放的粒子
• 击败音效 (槽位15) — 25个击杀时播放的音效
• 重置所有 (槽位22) — 一键清除所有特效选择

子菜单

6行界面，每页最多35个效果，底部控制栏:

• 返回 — 回到主菜单
• 上一页 / 下一页 — 翻页浏览
• 重置 — 清除当前类别选择
• 切换声调 (仅音效) — 低音/中音/高音 三档循环

物品状态显示

粒子 GUI (/aep)

54格界面，显示7种粒子样式分类入口: 身体环绕、头顶粒子、移动轨迹、箭矢轨迹、钓鱼轨迹、发光效果、背部粒子。底部有"重置所有粒子效果"按钮。

物品效果模式

手持带有 Lore 效果的物品时输入 /ae，会弹出物品效果模式选择界面，允许:

• 开关 Lore 击败效果 / Lore 攻击效果 / Lore 音效
• 调节 Lore 音效音量（低/中/高）

💀 击败特效

触发条件

当玩家 A 击杀玩家 B 时，在 B 的位置播放 A 选择的击败特效。每个特效可包含: 多组粒子、独立音效、闪电效果。

特效配置参数

内置特效摘选 (共50个)

完整列表: 游戏内 /ae list，或查看 ae/effects-kill.yml

⚔️ 攻击特效

触发条件

攻击时在被击位置播放粒子效果。冷却默认 5 tick（config.yml 中 attack-effect-cooldown）。

内置特效摘选 (共40个)

完整列表: /ae list 或 ae/effects-attack.yml

🔔 击败音效

三档声调系统

每种音效配置三档 pitch 值 (pitch-low/pitch-mid/pitch-high)。玩家在 GUI 中点击"切换声调"按钮循环切换。声调选择自动保存。

内置音效摘选 (共25个)

完整列表: /ae list 或 ae/effects-sound.yml

📜 Lore 物品效果

工作原理

当玩家手持物品的材质+Lore文本匹配规则时，自动触发绑定特效。Lore效果优先级高于玩家全局选择；未被Lore覆盖的类型仍使用全局选择。

匹配规则

• 按材质名分组（如 DIAMOND_SWORD、BOW、TRIDENT）
• Lore 用包含匹配（去色彩码后比较）
• 一条规则可同时绑定 kill-type / attack-type / sound-type
• 多条规则可叠加，先匹配到的类型优先
• 同时检查主手和副手
• 玩家可在 GUI 中对 Lore 效果开/关及调音量

配置示例

# ae/lore-effects.yml
lore-effects:
  DIAMOND_SWORD:
    - lore: "雷霆之怒"           # 物品Lore包含此文本即触发
      kill-type: lightning       # 击败特效ID
      attack-type: electric_shock # 攻击特效ID
      sound-type: explosion_pop  # 击败音效ID
    - lore: "击败效果-烈焰"
      kill-type: flame_pillar    # 只绑击败，其他类型用全局选择

  NETHERITE_SWORD:
    - lore: "暗影裁决"
      kill-type: warden_darkness
      attack-type: soul_flame
      sound-type: sculk_click

🌟 粒子效果总览

7种粒子样式

粒子来源

5种基础样式 (orbit/overhead/trail/arrow/fishing) 与以下两种粒子来源自动组合:

• 18种 Dust 颜色: 红/橙/黄/黄绿/绿/青/蓝/淡蓝/紫/品红/粉/棕/白/淡灰/灰/黑 + 随机色 + 彩虹色
• 35种非Dust粒子: 火焰/灵魂火焰/微焰/附魔/巫术/传送门/末地烛/逆传送门/不死图腾/鹦鹉螺/爱心/翠绿/樱花/雪花/白云/蜂蜜/孢子花/堆肥/水花/海豚/水滴/气泡/熔岩滴/烟雾/篝火烟/灰烬/绯红孢子/诡异孢子/幽匿之魂/暴击/魔法暴击/烟火/音符/电火花/涂蜡/刮铜/尘烟/荧光墨

颜色模式

权限格式: adventureeffect.particle.<样式>.<颜色/粒子ID>

💡 发光效果 v1.6

18种发光颜色

白/红/橙/黄/黄绿/绿/青/淡蓝/蓝/紫/品红/粉/灰/深灰/黑/深红/深蓝 + 彩虹(自动切换) + 随机色(随机变化)

实现方式

通过 Minecraft 计分板 Team 设置颜色 + setGlowing(true)。彩虹模式每 10 tick 切换色相，循环全部 16 色。

自动清理

• 玩家离线 → 自动移除发光 Team
• 插件停止 → 清理所有发光 Team
• 取消选择 → 立即移除发光

权限: adventureeffect.particle.glow.<颜色>

🦋 翅膀效果 v1.6

6种翅膀形状

30种翅膀效果 (摘选)

显示行为 v1.6.2

• 翅膀对齐: 始终紧贴玩家背面，随朝向自动旋转
• 移动时: 自动隐藏翅膀
• 静止时: 每 idle-tick-interval tick 持续显示（默认4）

可调参数 v1.6.2

权限: adventureeffect.particle.back.<效果ID>

⚙️ 配置详解

config.yml 主配置

settings:
  debug: false                    # 调试输出
  auto-save-interval: 10          # 自动保存间隔 (分钟, 0=仅关服保存)
  attack-effect-cooldown: 5       # 攻击特效冷却 (tick)
  kill-effect-delay: 2            # 击败特效延迟 (tick)
  particle-switch-cooldown: 3     # 粒子切换冷却 (秒, 0=无冷却)
  afk-particle-timeout: 30        # AFK超时 (秒, 0=禁用)
  projectile-landing-particles: false  # 投射物落地后是否继续粒子

gui:
  effects-per-page: 35            # 每页效果数 (最大35)
  main-menu-rows: 3               # 主菜单行数
  sub-menu-rows: 6                # 子菜单行数
  kill-button-slot: 11
  attack-button-slot: 13
  sound-button-slot: 15
  reset-all-slot: 22

permissions:
  kill-prefix: "adventureeffect.kill."
  attack-prefix: "adventureeffect.attack."
  sound-prefix: "adventureeffect.sound."
  particle-prefix: "adventureeffect.particle."

粒子效果配置 (aep/particles.yml)

全局默认参数 v1.6.2

particle-defaults:
  dust-size: 1.0        # Dust粒子大小 (0.1~4.0)
  count: 2              # 粒子数量
  spread-x: 0.1         # X轴扩散
  spread-y: 0.1
  spread-z: 0.1
  speed: 0.0            # 粒子速度
  tick-interval: 2      # 刷新间隔 (tick)

颜色定义

colors:
  red:
    name: "&c红色"
    rgb: "255,0,0"
    icon: RED_DYE
  random:
    name: "&e✦ 随机颜色"
    mode: random
    icon: FIREWORK_STAR

样式定义

styles:
  orbit:
    enabled: true
    display-name: "身体环绕"
    menu-icon: ENDER_EYE
    radius: 1.0             # orbit 专用
    orbs: 3                 # 轨道球数
    steps: 120              # 每圈步数
  overhead:
    head-offset: 2.2        # overhead 专用

🎨 自定义特效教程

添加自定义击败特效

# ae/effects-kill.yml — 在 kill-effects: 下添加
  my_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
      - type: DUST
        count: 20
        dust-color: "255,215,0"
        dust-size: 1.5
        offset-x: 0.3
        offset-y: 0.5
        offset-z: 0.3
    lightning-strike: false
    sound: ENTITY_ENDER_DRAGON_GROWL
    sound-volume: 1.0
    sound-pitch: 1.0
# 权限: adventureeffect.kill.my_effect

添加自定义击败音效

# ae/effects-sound.yml — 在 kill-sounds: 下添加
  my_sound:
    name: "&e🎵 自定义音效"
    icon: NOTE_BLOCK
    sound: BLOCK_NOTE_BLOCK_PLING
    volume: 1.0
    pitch-low: 0.5
    pitch-mid: 1.0
    pitch-high: 2.0
# 权限: adventureeffect.sound.my_sound

添加自定义翅膀效果

# aep/particles.yml — 在 back → effects: 下添加
    my_wing:
      name: "&a✦ 自定义翅膀"
      wing-shape: angel    # angel/demon/butterfly/dragon/fairy/phoenix
      particle: END_ROD
      icon: FEATHER
      count: 1
      speed: 0.01
# 权限: adventureeffect.particle.back.my_wing

添加新颜色 (自动应用到所有基础样式)

# aep/particles.yml — 在 colors: 下添加
  gold:
    name: "&6金色"
    rgb: "255,215,0"
    icon: GOLD_INGOT
# 自动生成: orbit_gold, overhead_gold, trail_gold, arrow_gold, fishing_gold

🔄 跨服同步 v1.5.8

架构

• MySQL — 持久化存储 (HikariCP)，ae_player_data + ae_particle_selections
• Redis — 缓存 + Pub/Sub 实时推送 (Jedis)
• BungeeCord/Velocity — 消息通道预留

工作流程

1. 玩家加入 → Redis缓存优先 → 未命中走MySQL
2. 切换特效 → 写入MySQL + Redis → Pub/Sub推送全部子服
3. 其他子服收到通知 → 从Redis读最新数据 → 更新内存

配置

sync:
  enabled: false         # 默认关闭，单服无需开启
  server-id: ""          # 每个子服应不同
  mysql:
    host: "localhost"
    port: 3306
    database: "adventureeffect"
    username: "root"
    password: ""
    table-prefix: "ae_"
    pool-size: 10
  redis:
    host: "localhost"
    port: 6379
    password: ""
    database: 0
    pool-size: 10
    key-prefix: "ae:"

🔗 PlaceholderAPI v1.5

占位符列表

安装 PlaceholderAPI 后自动挂接。返回名称已自动去除颜色代码。

⚡ 性能与优化

AFK 自动暂停

玩家静止超过 afk-particle-timeout 秒(默认30)后，暂停环绕和头顶粒子。移动后恢复。设为 0 禁用。

投射物落地停止

projectile-landing-particles: false(默认) — 箭矢/钓鱼竿落地后停止粒子。存活超过1200tick的追踪投射物自动清理。

非Dust粒子限流

非Dust粒子每次生成限制为1颗，避免高密度粒子影响性能。

翅膀智能显示

翅膀仅在玩家静止时生成粒子，移动时完全停止。

解锁庆祝系统

通过 /aep grant 授权时自动播放庆祝: 无伤害烟花 + Title 动画 + 升级音效。批量授予 5+ 时合并提示。

❓ 常见问题

Q: 粒子效果看不到？

A: ① 检查权限 ② 检查GUI中是否选择 ③ MC视频设置"粒子"→"全部" ④ AFK超时可能暂停

Q: 翅膀位置偏移？

A: 升级到 v1.6.2。微调 wing-offset(背部距离) 和 wing-height(垂直高度)。

Q: 如何批量解锁效果？

A: 用 LuckPerms 通配符: lp user Steve permission set adventureeffect.particle.orbit.* true

Q: 跨服同步开启后本地数据还有吗？

A: 有，playerdata.yml 仍保存备份。主数据以 MySQL 为准。

Q: 某些粒子在 1.20.1 看不到？

A: 部分新粒子在1.20.1不存在。插件尝试别名映射，失败则静默跳过。

Q: 如何关闭某种粒子样式？

A: aep/particles.yml 中将对应样式 enabled 设为 false。

Q: 发光效果和其他Team插件冲突？

A: 插件使用 ae_glow_ 前缀的Team名。如冲突可关闭: glow: enabled: false。

📝 更新日志

v1.6.3

• CONFIG softdepend 更新 — plugin.yml 新增 AdventureManage 为可选依赖，提升跨插件兼容性

v1.6.2

• FIX 翅膀对齐修复 — 修正yaw旋转公式，翅膀始终紧贴背面
• NEW 全局粒子默认参数 — particle-defaults 配置节
• NEW 翅膀可配置参数 — wing-offset/scale/spread/height/idle-tick-interval
• IMPROVED 文件结构重组 — 配置分离到 ae/ 和 aep/

v1.6.0

• NEW 35种非Dust粒子 — 自动与5种样式组合
• NEW 发光效果 (GLOW) — 16色+彩虹+随机
• NEW 翅膀效果 (BACK) — 6翅形×5粒子=30效果
• IMPROVED GUI 扩展至7样式

v1.5.8

• NEW 跨服同步 — MySQL + Redis Pub/Sub
• CONFIG 新增 sync 配置区块

v1.5.1

• NEW AFK性能优化 — 静止超时停止粒子
• NEW 投射物落地停止
• NEW 解锁庆祝系统

v1.5

• NEW 玩家粒子效果系统 — 5样式×18颜色
• NEW 粒子GUI + /aep命令
• NEW PlaceholderAPI支持 — 12个占位符

v1.3

• NEW Lore效果检测 — 材质+Lore关键词自动触发
• NEW 物品效果GUI

v1.2

• IMPROVED 无效粒子/音效静默处理
• NEW 双版本构建 mc1201/mc1214