语言： 中文 | English

SpecialItem

一个 Minecraft Paper 插件（Kotlin），用于实现可升级+绑定玩家的特殊物品系统。

⚠️ 重要说明（设计定位）

SpecialItem 并非开箱即用型插件。

它更像是一个「特殊物品开发框架 / 示例集合」，主要面向 插件开发者：

• 你可以 继承并扩展 SpecialItemBase 来实现自己的特殊物品
• 也可以 修改 / 删除 仓库中已有的物品实现
• 内置物品仅作为示例，不保证适合所有服务器的玩法、平衡或经济系统

如果你期望的是“丢进 plugins 就能直接玩的成品插件”，那它大概率 不适合你； 如果你希望 快速搭建一个可升级+绑定玩家的特殊物品体系并在此基础上二次开发，那它正是为此而生。

(这个玩意纯粹是为了我自己的服务器方便而写的，不过其中的一些代码也许可以帮到别人，仅此而已)

---

基本信息

• 插件名：SpecialItem

• 版本：1.0.0

• 作者：AxiumYu

• Minecraft API：Paper / Bukkit (api-version: 1.21)

• 开发语言：Kotlin

• 前置依赖：

  • XConomy（用于货币与升级消耗）（可以自行替换为例如Vault等其他实现，不过还没做封装，下次应该会加上）

其中最重要的部分是：

SpecialItemBase —— 整个插件的设计核心

---

核心设计理念

1. 所有特殊物品 = SpecialItemBase

每一个特殊物品：

• 都是一个 独立的 Kotlin 类

• 继承自 SpecialItemBase

• 自行定义：

  • 最大等级 (maxLevel)
  • 升级消耗（BigDecimal，与经济系统解耦）
  • 物品材质、稀有度、附魔范围
  • 行为逻辑（事件监听）

插件本身 不关心你具体做了什么物品，只负责：

• 注册
• 识别
• 升级
• 绑定玩家

2. 玩家绑定与升级系统

SpecialItemBase 内部已处理：

• 物品唯一标识（名字，材料，Lore，等级上限等等）
• 绑定玩家（Owner）
• 等级存储与升级
• Lore 自动更新

示例 Lore 结构：

• 描述文本
• 当前等级 / 最大等级
• 绑定玩家名

你只需要关注：

“这个物品在某个等级下会做什么？”

---

内置示例物品（仅示例用途）

当前仓库中包含以下示例实现：

• WindStaff：风之法杖，使用时消耗饥饿值，向视野前方移动一段距离
• ExperienceStorge：经验池，方便的经验存取工具
• IronElevator：铁块电梯，方便上下移动
• ItemMagnet：物品磁铁，吸取一定范围内的物品

⚠️ 再次强调：

这些物品 只是示例实现，并不保证：

• 平衡性
• 性能适配
• 与你服务器玩法的契合度

非常推荐：

• 直接删除它们
• 或仅保留你需要的逻辑片段

---

命令说明

插件提供一个主命令：

/specialitem
/si

用法

/si get <id> 
// 获取一个特殊物品
/si upgrade <id>
// 升级一个特殊物品
/si transfer <id> [confirm]
// 转移一个特殊物品到其他物品上（更改绑定）

（具体行为以 SpecialItemCommand.kt 中实现为准）

---

开发者指南（最重要部分）

创建你自己的特殊物品

1. 新建一个类并继承 SpecialItemBase, 然后实现需要的成员
2. 注册事件监听（SpecialItemBase 已实现 Listener）
3. 在插件启用时注册该物品（通过 ItemManager）

你可以自由修改的内容

• 升级消耗
• Lore 显示格式
• 玩家绑定规则
• 经济系统（目前基于 XConomy）
• 触发方式

插件 不会限制你这样做。

---

构建与安装（开发向）

./gradlew build

生成的 Jar 位于：

build/libs/SpecialItem-X.X.X.jar

放入 Paper 服务器的 plugins/ 目录即可。

---

适合谁使用？

✅ 适合：

• 想自己写特殊物品的插件开发者
• 不想从零开始处理 PDC / 升级 / Lore 的人
• 希望有一个“可拆解、可改造”的物品系统骨架

❌ 不适合：

• 只想直接装插件开服的服主
• 不愿意改代码、调平衡的人

---

许可

所有源代码遵循MIT协议。