[MD]
**吸铁石 XiTieShi** 是一个围绕原版磁石扩展的小型 Paper 插件。它不会引入复杂系统，而是把 Minecraft 原本较少使用的“磁石”改造成真正有用的工具：玩家获得磁力附魔书后，可以在铁砧中把磁力附加到磁石上，从而得到可吸取掉落物的“吸铁石”。
玩家手持吸铁石右键，可以把附近掉落物聚拢到身边；潜行左键可以在小、中、大三档普通吸力间循环切换，潜行右键则独立开关大马力，在更大范围内制造带粒子与音效的磁力漩涡。插件所有提示、物品名称、Lore、日志和命令反馈均为中文，开箱即用。
### 核心功能
- **原版友好**：基于原版磁石和铁砧流程，不破坏生存体验。
- **磁力附魔书**：管理员可发放专用附魔书，用于制作吸铁石。
- **三档普通吸力**：潜行左键循环切换小、中、大吸力，默认水平范围分别为 2.5、5、8 格。
- **独立大马力**：潜行右键开关，开启后可在 16 格范围内吸取掉落物并产生磁力漩涡。
- **四级磁力附魔**：磁力 I 仅小吸力；II 解锁中吸力；III 解锁大吸力；X 解锁全部吸力与大马力。
- **副手自动吸附**：将吸铁石放入副手即可自动持续吸取，无需手动开启。
- **完整动画反馈**：附魔升级、档位切换、大马力开关、主动吸取和副手运行均有独立动画与音效。
- **视觉强度可调**：支持关闭动画或音效，并提供低、标准、高三档粒子密度。
- **轻量运行**：无需数据库，无需额外配置，放入 plugins 目录即可使用。
- **全中文体验**：玩家提示、命令反馈、物品描述均为中文。
### 使用方法
1. 管理员使用命令发放指定等级的磁力附魔书。
2. 玩家将“磁石”和“磁力附魔书”放入铁砧。
3. 消耗 3 级经验后获得“吸铁石”。
4. 手持吸铁石右键吸取附近掉落物。
5. 手持吸铁石潜行左键循环切换当前等级可用的普通吸力；磁力 X 可潜行右键开关大马力。
6. 将吸铁石放入副手，可自动持续吸附。
### 命令
| 命令 | 说明 | 权限 |
| --- | --- | --- |
| `/xitieshi givebook <I\|II\|III\|X> [玩家] [数量]` | 给予指定等级的磁力附魔书 | `xitieshi.command.givebook` |
### 权限
| 权限 | 默认 | 说明 |
| --- | --- | --- |
| `xitieshi.command.givebook` | OP | 允许使用命令获取磁力附魔书 |
### 合成与玩法说明
- 材料：原版磁石 + 磁力附魔书
- 操作：在铁砧中合成
- 经验消耗：3 级
- 磁力 I：仅可使用小吸力
- 磁力 II：可使用小、中吸力
- 磁力 III：可使用小、中、大吸力
- 磁力 X：可使用全部普通吸力和独立大马力
- 小吸力：水平 2.5 格、垂直 1.5 格，适合身边精准拾取
- 中吸力：水平 5 格、垂直 3 格，适合日常采集
- 大吸力：水平 8 格、垂直 5 格，适合较大场地
- 大马力：独立开关，水平和垂直 16 格，并启用磁力漩涡效果
### 适用场景
- 生存服：减少玩家重复捡物品的疲劳感。
- 养老服：提升挖矿、砍树、农场收集体验。
- RPG / 轻魔法服：作为可控的功能型道具或活动奖励。
- 小型服务器：无需配置即可部署，维护成本低。
### 兼容性
- 服务端：Paper 及兼容 Paper API 的服务端
- API 版本：1.20
- Java：17+
> 建议优先在 Paper 1.20.4 环境使用。其他兼容版本请先在测试服验证。
### 安装方法
1. 下载插件 jar 文件。
2. 将 jar 放入服务器 `plugins` 文件夹。
3. 重启服务器。
4. 使用 `/xitieshi givebook <I|II|III|X> [玩家] [数量]` 发放指定等级的磁力附魔书。
### 更新日志
#### 1.3.2
- 吸铁石无论位于主手还是副手，都不能作为磁石方块放置。
- 放置拦截不会影响主手使用其他物品或与方块交互。
- 增加限频的放置阻止提示，并在取消后同步玩家背包。
- 修复副手与手动持续模式切换时可能重复播放启动反馈的问题。
#### 1.3.1
- 新增按磁力等级递增的铁砧附魔动画。
- 新增小、中、大吸力档位切换磁环。
- 新增大马力开启扩张与关闭收束动画。
- 新增主动扫描、吸取启动、物品轨迹和抵达反馈。
- 新增副手启动动画与低频环绕光点，不持续刷屏。
- 新增动画、音效总开关以及三级粒子密度配置。
#### 1.2.0
- 新增磁力 I、II、III、X 四种等级附魔书，并按等级限制可用吸力。
- 铁砧支持使用更高级磁力附魔书继续升级已有吸铁石。
- 吸铁石放入副手后自动持续吸附。
- 旧版吸铁石自动按磁力 X 迁移，保留原有能力。
#### 1.1.1
- 普通模式新增小、中、大三档吸力预设，潜行左键循环切换。
- 大马力恢复为独立开关，潜行右键切换，关闭后返回此前普通档位。
- 三档普通吸力和大马力的范围与速度均可分别配置。
- 兼容旧版普通与大马力吸铁石数据。
[/MD]
