SpecialItem

<details> <summary>中文</summary> # SpecialItem 一个 **Minecraft Paper 插件（Kotlin）**，用于实现**可升级+绑定玩家的特殊物品系统**。 ⚠️ **重要说明** > **SpecialItem 并非开箱即用型插件。** > > 它更像是一个「**特殊物品开发框架 / 示例集合**」，主要面向 **插件开发者**： > > * 你可以 **继承并扩展 `SpecialItemBase`** 来实现自己的特殊物品 > * 也可以 **修改 / 删除** 仓库中已有的物品实现 > * **内置物品仅作为示例**，不保证适合所有服务器的玩法、平衡或经济系统 如果你期望的是“丢进 plugins 就能直接玩的成品插件”，那它大概率 **不适合你**； 如果你希望 **快速搭建一个可升级+绑定玩家的特殊物品体系并在此基础上二次开发**，那它正是为此而生。 *(这个玩意纯粹是为了我自己的服务器方便而写的，不过其中的一些代码也许可以帮到别人，仅此而已)* --- ## 基本信息 * **插件名**：SpecialItem * **作者**：AxiumYu * **Minecraft API**：Paper / Bukkit (`api-version: 1.21`) * **开发语言**：Kotlin * **前置依赖**： * (https://github.com/YiC200333/XConomyAPI)（用于货币与升级消耗）（可以自行替换为例如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> // 转移一个特殊物品到其他物品上（更改绑定） ``` （具体行为以 `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协议。 </details> <details> <summary>English</summary> # 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**: * (https://github.com/YiC200333/XConomyAPI) 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 c