SpecialItem

SpecialItem

一个 可升级+绑定玩家的特殊物品系统，用于实现可升级+绑定玩家的特殊物品系统。

⚠️ 重要说明

> 内置物品仅作为示例 > > 它更像是一个「内置物品仅作为示例」，主要面向 内置物品仅作为示例： > > * 你可以 内置物品仅作为示例 来实现自己的特殊物品 > * 也可以 内置物品仅作为示例 仓库中已有的物品实现 > * 内置物品仅作为示例，不保证适合所有服务器的玩法、平衡或经济系统

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

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

---

基本信息

* 前置依赖：SpecialItem * 前置依赖：AxiumYu * 前置依赖：Paper / Bukkit (`api-version: 1.21`) * 前置依赖：Kotlin * 前置依赖：

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

其中最重要的部分是：

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

---

设计理念

1. 所有特殊物品 = `SpecialItemBase`

每一个特殊物品：

* 都是一个 独立的 Kotlin 类 * 继承自 `SpecialItemBase` * 自行定义：

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

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

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

2. 玩家绑定与升级系统

`SpecialItemBase` 内部已处理：

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

示例 Lore 结构：

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

你只需要关注：

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

---

内置示例

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

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

⚠️ 再次强调：

> 这些物品 只是示例实现，并不保证： > > * 平衡性 > * 性能适配 > * 与你服务器玩法的契合度

非常推荐：

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

---

命令说明

插件提供一个主命令：

``` /specialitem /si ```

用法

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

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

---

开发者指南

创建你自己的特殊物品

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

你可以自由修改的内容

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

插件 不会限制你这样做。

---

构建与安装（开发向）

```bash ./gradlew build ```

生成的 Jar 位于：

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

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

---

适合谁使用？

✅ 适合：

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

❌ 不适合：

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

---

许可

所有源代码遵循MIT协议。

SpecialItem

A upgradeable, player-bound special item system designed to build an upgradeable, player-bound special item system.

⚠️ Important Notice (Project Positioning)

> not guaranteed > > It is closer to a not guaranteed, primarily targeting not guaranteed: > > * You can not guaranteed to implement your own special items > * You are free to not guaranteed the built-in item implementations > * not guaranteed 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

* Dependencies: SpecialItem * Dependencies: AxiumYu * Dependencies: Paper / Bukkit (`api-version: 1.21`) * Dependencies: 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:

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

⚠️ Once again:

> These items are not guaranteed 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)

```bash ./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 modifiable and extensible item-system skeleton * 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.