中文

SpecialItem

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

⚠️ 重要说明

SpecialItem 并非开箱即用型插件。

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

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

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

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

---

基本信息

• 插件名：SpecialItem

• 作者：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协议。

English

SpecialItem

A Minecraft Paper plugin (Kotlin) designed to build an upgradeable, player-bound special item system.

⚠️ Important Notice (Project Positioning)

SpecialItem is NOT a plug-and-play plugin.

It is closer to a “special item development framework / example collection”, primarily targeting plugin developers:

• You can extend SpecialItemBase to implement your own special items
• You are free to modify or remove the built-in item implementations
• All built-in items are examples only and are not guaranteed to fit every server’s gameplay, balance, or economy

If you are looking for a finished plugin that you can just drop into the plugins folder and start playing with, then this project is probably not for you.

If you want to quickly build an upgradeable + player-bound special item system and extend it yourself, then this project is made exactly for that purpose.

(This plugin was written purely for my own server’s convenience. Some parts of the code might be useful to others — nothing more, nothing less.)

---

Basic Information

• Plugin Name: SpecialItem

• Author: AxiumYu

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

• Language: Kotlin

• Dependencies:

  • XConomy Used for currency handling and upgrade costs (You may replace it with alternatives such as Vault, but abstraction is not implemented yet — planned for the future)

The most important part of this project is:

SpecialItemBase — the core of the entire design

---

Core Design Concepts

1. Every Special Item = SpecialItemBase

Each special item:

• Is an independent Kotlin class

• Extends SpecialItemBase

• Defines its own:

  • Maximum level (maxLevel)
  • Upgrade cost (BigDecimal, decoupled from the economy implementation)
  • Material, rarity, enchantment range
  • Behavior logic (event handling)

The plugin itself does not care what your item actually does. It only handles:

• Registration
• Identification
• Upgrading
• Player binding

---

2. Player Binding & Upgrade System

SpecialItemBase already handles:

• Item identification (name, material, lore, max level, etc.)
• Player binding (owner)
• Level storage and upgrading
• Automatic lore updates

Example lore structure:

• Description text
• Current level / max level
• Bound player name

All you need to focus on is:

“What does this item do at a given level?”

---

Built-in Example Items (Examples Only)

The repository currently includes the following example implementations:

• WindStaff A wind staff that consumes hunger to dash the player forward
• ExperienceStorage A convenient tool for storing and retrieving experience points
• IronElevator An iron-block-based elevator for vertical movement
• ItemMagnet Attracts nearby dropped items within a certain range

⚠️ Once again:

These items are examples only and are not guaranteed to be:

• Balanced
• Performance-optimized
• Suitable for your server’s gameplay

It is strongly recommended to:

• Remove them entirely
• Or keep only the parts of the logic you actually need

---

Commands

The plugin provides a main command:

/specialitem
/si

Usage

/si get <id>
# Get a special item

/si upgrade <id>
# Upgrade a special item

/si transfer <id> [confirm]
# Transfer a special item to another item (change ownership binding)

(Exact behavior is defined in SpecialItemCommand.kt.)

---

Developer Guide (Most Important Section)

Creating Your Own Special Item

1. Create a new class extending SpecialItemBase and implement the required members
2. Register event listeners (SpecialItemBase already implements Listener)
3. Register the item via ItemManager during plugin initialization

---

Things You Are Free to Modify

• Upgrade cost logic
• Lore formatting
• Player binding rules
• Economy system (currently XConomy-based)
• Trigger conditions / interaction logic

The plugin does not restrict you from doing any of these.

---

Build & Installation (Developer-Oriented)

./gradlew build

The generated JAR can be found at:

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

Place it into the Paper server’s plugins/ directory.

---

Who Is This For?

✅ Suitable for:

• Plugin developers who want to write their own special items
• Developers who don’t want to reimplement PDC / upgrade / lore logic from scratch
• Those looking for a modifiable and extensible item-system skeleton

❌ Not suitable for:

• Server owners looking for a ready-to-use gameplay plugin
• Anyone unwilling to modify code or rebalance mechanics

---

License

All source code is released under the MIT License.