📥 安装与入门

依赖

安装步骤

1. 将 AdventureLib-2.5.0.jar 放入 plugins/ 目录
2. 将 AdventureItems-1.0.0.jar 放入 plugins/ 目录
3. 启动/重启服务器
4. 插件自动生成配置文件和示例物品

快速入门 — GUI 编辑器 (推荐)

1. /aitems browse — 打开类型浏览器
2. 点击 "剑" 类型 → 进入物品列表
3. 点击 "新建物品" → 输入物品ID (如 MY_SWORD)
4. 在编辑器中设置: 材质 → DIAMOND_SWORD, 名称 → &c&l烈焰之剑, 攻击伤害 → 15
5. 点击 "技能" 图标 → 添加技能 (如 AOE)
6. 设置触发方式、冷却、属性

快速入门 — YAML 配置

# plugins/AdventureItems/items/sword.yml
MY_SWORD:
  material: DIAMOND_SWORD
  display-name: "&c&l烈焰之剑"
  description:
    - "&7一把蕴含烈焰之力的神剑"
  unbreakable: true
  base:
    ATTACK_DAMAGE: 15.0
    CRITICAL_STRIKE_CHANCE: 25.0
  powers:
    0:
      type: AOE
      trigger: RIGHT_CLICK
      cooldown: 5.0
      radius: 5.0
      damage: 8.0
      particle: FLAME

获取物品

/aitems give SWORD MY_SWORD          # 给自己
/aitems give SWORD MY_SWORD 1 Steve  # 给指定玩家

目录结构

plugins/AdventureItems/
├── config.yml          # 主配置
├── messages.yml        # 消息模板
├── item-types.yml      # 物品类型定义
├── lore-format.yml     # Lore 格式模板
└── items/              # 物品数据 (按类型分文件)
    └── sword.yml       # 剑类物品

📦 物品类型 (20 种)

武器类 (parent: weapon)

防具类 (parent: armor)

其他类

自定义类型

# item-types.yml
DAGGER:
  name: "§c匕首"
  material: IRON_SWORD
  parent: weapon
  displayed: true
  available-stats:
    - all

📄 YAML 物品配置

基础格式

ITEM_ID:
  material: DIAMOND_SWORD              # 原版材质
  display-name: "&c&l烈焰之剑"         # 显示名
  description:                          # 描述/Lore
    - "&7蕴含烈焰之力的神剑"
  custom-model-data: 1001              # 资源包模型ID
  unbreakable: true                    # 不可破坏
  base:                                # 属性
    ATTACK_DAMAGE: 15.0
    ATTACK_SPEED: 1.8
    CRITICAL_STRIKE_CHANCE: 25.0
    TIER: "传说"
  powers:                              # 技能
    0:
      type: AOE
      trigger: RIGHT_CLICK
      cooldown: 5.0
      mana-cost: 20.0
      radius: 5.0
      damage: 8.0
      particle: FLAME

完整示例 — 多技能组合武器

TEST_COMBO:
  material: NETHERITE_SWORD
  display-name: "&c&l&n全能战剑"
  description:
    - "&7右键: AOE范围伤害"
    - "&7Shift+右键: 冲刺"
    - "&7攻击: 吸血30%"
    - "&7潜行: 冰冻周围"
  unbreakable: true
  base:
    ATTACK_DAMAGE: 20.0
    CRITICAL_STRIKE_CHANCE: 30.0
  powers:
    0:
      type: AOE
      trigger: RIGHT_CLICK
      cooldown: 5.0
      radius: 5.0
      damage: 6.0
    1:
      type: SHIELD
      trigger: RIGHT_CLICK
      cooldown: 15.0
      absorption: 8.0
      duration-ticks: 200
    2:
      type: DASH
      trigger: SHIFT_RIGHT_CLICK
      cooldown: 5.0
      distance: 10.0
      damage: 4.0
    3:
      type: LIFE_STEAL
      trigger: HIT
      cooldown: 0.5
      percentage: 30.0
    4:
      type: FREEZE
      trigger: SNEAK
      cooldown: 10.0
      radius: 5.0
      duration-ticks: 80

📊 属性系统概览

AdventureItems 注册了 120+ 个属性，分为 10 大分类：

基础属性 (BASE)

⚔️ 战斗属性 (COMBAT)

🛡️ 防御属性 (DEFENSE)

✨ 附加属性 & 其他分类

附加属性 (EXTRA_ATTRIBUTE)

消耗品属性 (CONSUMABLE)

其他分类

ABILITY — 技能/命令

ABILITIES、COMMANDS、LEFT_CLICK_SCRIPT、RIGHT_CLICK_SCRIPT

GEM_UPGRADE — 宝石/升级

GEM_SOCKETS、GEM_COLOR、GEM_UPGRADE_SCALING、ITEM_TYPE_RESTRICTION、COMPATIBLE_TYPES、COMPATIBLE_IDS、COMPATIBLE_MATERIALS、UPGRADE、REPAIR_POWER、REPAIR_POWER_PERCENT、REPAIR_REFERENCE、CRAFTING、CRAFT_PERMISSION

PERMANENT — 永久效果

PERM_EFFECTS、GRANTED_PERMISSIONS、ELEMENTS、ARROW_POTION_EFFECTS、PROJECTILE_PARTICLES

DISABLE — 禁用交互

APPEARANCE — 外观

UNBREAKABLE、UNSTACKABLE、TWO_HANDED、HIDE_DURABILITY_BAR、HIDE_DYE、HIDE_ARMOR_TRIM、AUTOSMELT、BOUNCING_CRACK、DYE_COLOR、TRIM_MATERIAL、TRIM_PATTERN、SHIELD_PATTERN、CUSTOM_SOUNDS、PICKAXE_POWER、DISABLE_DEATH_DROP 等 25+ 个

💥 技能系统 (20 种)

基础技能 (10 种)

高级技能 (10 种)

AOE — 范围伤害

以玩家为中心对周围所有生物造成伤害。

PROJECTILE — 弹射物

可用类型：ARROW, FIREBALL, SMALL_FIREBALL, SNOWBALL, EGG, ENDER_PEARL, TRIDENT, WITHER_SKULL

DASH — 冲刺

SHIELD — 护盾

FREEZE — 冰冻

STUN — 眩晕

PULL — 拉拽

THROW — 抛投

LIFE_STEAL — 生命窃取

SUMMON — 召唤

技能绑定

每个技能绑定包含以下通用配置：

一个物品可以绑定多个技能：

powers:
  0:
    type: AOE
    trigger: RIGHT_CLICK
    cooldown: 5.0
  1:
    type: SHIELD
    trigger: SHIFT_RIGHT_CLICK
    cooldown: 15.0
  2:
    type: LIFE_STEAL
    trigger: HIT
    cooldown: 0.5

⚡ 触发器 (17 种)

🖥️ GUI 编辑器

编辑器流程

/aitems browse
    │
    ▼
┌──────────────────┐
│  类型浏览器       │  选择物品类型
│  TypeBrowserGui   │
└────────┬─────────┘
         ▼
┌──────────────────┐
│  物品浏览器       │  查看/新建/删除物品
│  ItemBrowserGui   │
└────────┬─────────┘
         ▼
┌──────────────────┐
│  属性编辑器       │  编辑 120+ 属性
│  ItemEditorGui    │
└────────┬─────────┘
         ▼
┌──────────────────┐
│  技能编辑器       │  添加/编辑/删除技能
│  PowerEditorGui   │
└──────────────────┘

类型浏览器

显示所有 item-types.yml 中定义的物品类型，每个类型显示为对应材质的图标。点击进入该类型的物品列表。

物品浏览器

属性编辑器

• 每页显示 21 个可用属性 (3行 × 7列)，按分类排序
• 左键点击 — 进入聊天输入模式设置新值
• 右键点击 — 清除该属性值
• 输入 cancel 取消编辑
• 材质 (MATERIAL) 属性支持模糊匹配：输入 diamond 自动搜索匹配

技能编辑器

⌨️ 命令与权限

玩家命令 — /aitems

give 命令详解

/aitems give SWORD TEST_AOE          # 给自己 1 把
/aitems give SWORD TEST_AOE 5        # 给自己 5 把
/aitems give SWORD TEST_AOE 1 Steve  # 给玩家 Steve

管理命令 — /aitemsadmin

权限节点

⚙️ 配置文件

config.yml

# ═══════════════════════════════════════
# AdventureItems 配置文件
# ═══════════════════════════════════════

# 物品实时更新 Ticker
ticker:
  # 每 tick 处理多少个玩家的背包更新
  # 小服 5-10, 中服 3-5, 大服 1-3
  players-per-tick: 5

# 钩子
hooks:
  placeholderapi: true    # 启用 PlaceholderAPI

# 调试模式
debug: false

Lore 格式模板

# lore-format.yml
default:
  - "{description}"       # 物品描述
  - ""
  - "{stats}"             # 所有属性的 lore 行
  - ""
  - "&8类型: {type}"       # 物品类型名
  - "&8品质: {tier}"       # 品质/稀有度

通过物品的 LORE_FORMAT stat 指定使用的模板：

MY_SWORD:
  base:
    LORE_FORMAT: "weapon_fancy"

PlaceholderAPI 变量

🎮 实战案例

⚔️ 炎龙战士套装 — 近战暴击流

适合近战玩家，高暴击配合吸血实现持续作战能力。右键 AOE 清怪，攻击自动吸血续航。

主武器 — 炎龙斩

# items/sword.yml
DRAGON_BLADE:
  material: NETHERITE_SWORD
  display-name: "&c&l炎龙斩"
  description:
    - "&7传说中的炎龙之剑"
    - "&7&o「斩尽一切阻碍」"
    - ""
    - "&e右键 &8- &c范围火焰伤害"
    - "&e攻击 &8- &a30% 吸血"
  unbreakable: true
  base:
    ATTACK_DAMAGE: 18.0
    ATTACK_SPEED: 1.6
    CRITICAL_STRIKE_CHANCE: 35.0
    CRITICAL_STRIKE_POWER: 180.0
    LIFESTEAL: 5.0
    TIER: "&6&l传说"
  powers:
    0:
      type: AOE
      trigger: RIGHT_CLICK
      cooldown: 6.0
      radius: 5.0
      damage: 8.0
      particle: FLAME
    1:
      type: LIFE_STEAL
      trigger: HIT
      cooldown: 0.5
      percentage: 30.0
    2:
      type: SOUND
      trigger: HIT
      cooldown: 0.3
      sound: ENTITY_BLAZE_SHOOT
      volume: 0.5
      pitch: 1.5

配套防具

# items/helmet.yml
DRAGON_HELM:
  material: NETHERITE_HELMET
  display-name: "&c&l炎龙战盔"
  unbreakable: true
  base:
    ARMOR: 5.0
    ARMOR_TOUGHNESS: 3.0
    MAX_HEALTH: 10.0
    CRITICAL_STRIKE_CHANCE: 5.0
    FIRE_DAMAGE_REDUCTION: 30.0
    TIER: "&6&l传说"

# items/chestplate.yml
DRAGON_CHEST:
  material: NETHERITE_CHESTPLATE
  display-name: "&c&l炎龙战甲"
  unbreakable: true
  base:
    ARMOR: 10.0
    ARMOR_TOUGHNESS: 5.0
    MAX_HEALTH: 20.0
    DAMAGE_REDUCTION: 8.0
    FIRE_DAMAGE_REDUCTION: 30.0
    TIER: "&6&l传说"

🔮 星辰法师套装 — 远程法术流

法杖类武器，技能消耗法力值，右键发射弹射物，Shift+右键冰冻敌人。需要搭配高法力恢复装备。

# items/staff.yml
STAR_STAFF:
  material: BLAZE_ROD
  display-name: "&d&l星辰法杖"
  custom-model-data: 2001
  description:
    - "&7凝聚星辰之力的法杖"
    - ""
    - "&d右键 &8- &b发射寒冰弹 &7(消耗 15 法力)"
    - "&d潜行+右键 &8- &b冰冻范围 &7(消耗 40 法力)"
    - "&d攻击 &8- &e闪电打击"
  unbreakable: true
  base:
    ATTACK_DAMAGE: 8.0
    MAGIC_DAMAGE: 25.0
    MAX_MANA: 100.0
    MANA_REGENERATION: 5.0
    SKILL_DAMAGE: 15.0
    TIER: "&d&l史诗"
  powers:
    0:
      type: PROJECTILE
      trigger: RIGHT_CLICK
      cooldown: 2.0
      mana-cost: 15.0
      projectile-type: SNOWBALL
      speed: 2.5
      damage: 12.0
    1:
      type: FREEZE
      trigger: SHIFT_RIGHT_CLICK
      cooldown: 12.0
      mana-cost: 40.0
      radius: 6.0
      duration-ticks: 100
      slow-level: 4
    2:
      type: LIGHTNING
      trigger: HIT
      cooldown: 3.0
      mana-cost: 10.0

🛡️ 不朽堡垒套装 — 高防御减伤流

极致防御配置，叠加减伤、格挡、闪避和护盾。适合 Boss 战中担任前排。

# items/sword.yml
FORTRESS_SWORD:
  material: IRON_SWORD
  display-name: "&9&l守护之剑"
  description:
    - "&7坚不可摧的堡垒之剑"
    - ""
    - "&9右键 &8- &e激活护盾 (8点吸收)"
    - "&9被击 &8- &e反弹眩晕"
  unbreakable: true
  base:
    ATTACK_DAMAGE: 10.0
    DEFENSE: 8.0
    BLOCK_POWER: 40.0
    BLOCK_RATING: 30.0
    DAMAGE_REDUCTION: 10.0
    KNOCKBACK_RESISTANCE: 0.6
    TIER: "&9&l稀有"
  powers:
    0:
      type: SHIELD
      trigger: RIGHT_CLICK
      cooldown: 20.0
      absorption: 8.0
      duration-ticks: 200
    1:
      type: STUN
      trigger: TAKE_HIT
      cooldown: 8.0
      radius: 3.0
      duration-ticks: 40

# items/chestplate.yml
FORTRESS_CHEST:
  material: DIAMOND_CHESTPLATE
  display-name: "&9&l不朽胸甲"
  unbreakable: true
  base:
    ARMOR: 12.0
    ARMOR_TOUGHNESS: 6.0
    MAX_HEALTH: 40.0
    DAMAGE_REDUCTION: 15.0
    PVE_DAMAGE_REDUCTION: 10.0
    DODGE_RATING: 10.0
    TIER: "&9&l稀有"

⚡ 疾风刺客 — PvP 爆发流

冲刺接近 → 高暴击爆发 → 抛投打断。短时间内打出最大伤害，击杀后脱离。

# items/sword.yml
ASSASSIN_BLADE:
  material: DIAMOND_SWORD
  display-name: "&e&l疾风之刃"
  description:
    - "&7刺客的专属武器"
    - ""
    - "&e右键 &8- &c冲刺突进 (10格)"
    - "&eShift+右键 &8- &c抛投敌人"
    - "&e攻击 &8- &a25% 吸血"
  unbreakable: true
  base:
    ATTACK_DAMAGE: 14.0
    ATTACK_SPEED: 2.0
    CRITICAL_STRIKE_CHANCE: 40.0
    CRITICAL_STRIKE_POWER: 200.0
    PVP_DAMAGE: 15.0
    MOVEMENT_SPEED: 0.03
    TIER: "&e&l史诗"
    DISABLE_DROPING: true
  powers:
    0:
      type: DASH
      trigger: RIGHT_CLICK
      cooldown: 8.0
      distance: 10.0
      damage: 5.0
      damage-radius: 2.5
    1:
      type: THROW
      trigger: SHIFT_RIGHT_CLICK
      cooldown: 10.0
      radius: 4.0
      upward-force: 1.8
      outward-force: 0.8
    2:
      type: LIFE_STEAL
      trigger: HIT
      cooldown: 1.0
      percentage: 25.0

🧪 冒险者补给包

配套消耗品：治疗药剂、法力药剂、增强卷轴。为冒险者提供战斗续航。

# items/consumable.yml
HEAL_POTION:
  material: POTION
  display-name: "&a&l生命药剂"
  description:
    - "&7恢复 10 点生命值"
    - "&7冷却 30 秒"
  base:
    RESTORE_HEALTH: 10.0
    ITEM_COOLDOWN: 30.0
    COOLDOWN_REFERENCE: "potion_heal"
    MAX_CONSUME: 1
    TIER: "&a普通"

MANA_POTION:
  material: POTION
  display-name: "&b&l法力药剂"
  description:
    - "&7恢复 50 点法力值"
    - "&7冷却 20 秒"
  base:
    RESTORE_MANA: 50.0
    ITEM_COOLDOWN: 20.0
    COOLDOWN_REFERENCE: "potion_mana"
    MAX_CONSUME: 1
    TIER: "&b稀有"

BUFF_SCROLL:
  material: PAPER
  display-name: "&6&l力量卷轴"
  custom-model-data: 3001
  description:
    - "&7使用后获得力量II，持续 60 秒"
  base:
    MAX_CONSUME: 1
    TIER: "&e史诗"
  powers:
    0:
      type: POTION_EFFECT
      trigger: CONSUME
      cooldown: 120.0
      effect: INCREASE_DAMAGE
      duration: 1200
      amplifier: 1
    1:
      type: MESSAGE
      trigger: CONSUME
      cooldown: 120.0
      message: "&6&l✦ &e你感受到了强大的力量涌入体内！"

❓ 常见问题

base:
  DISABLE_DROPING: true      # 禁止丢弃
  DISABLE_CRAFTING: true     # 禁止合成
  DISABLE_ENCHANTING: true   # 禁止附魔
  DISABLE_SMELTING: true     # 禁止冶炼
  DISABLE_INTERACTION: true  # 禁止交互

# 这两把武器共享冷却计时器
SWORD_A:
  base:
    COOLDOWN_REFERENCE: "weapon_group_1"

SWORD_B:
  base:
    COOLDOWN_REFERENCE: "weapon_group_1"

# 宝石
ATK_GEM:
  material: EMERALD
  display-name: "&c&l攻击宝石"
  base:
    GEM_COLOR: "RED"
    ATTACK_DAMAGE: 5.0

# 武器（带两个红色插槽）
MY_SWORD:
  base:
    GEM_SOCKETS: "RED,RED"