Magic3 — Minecraft 魔法插件 (v3.0.0)

仿照 CooStack/UsefulMagic（GPL-3.0）的设计思路，用 Paper API 1.21+ 重新实现的完整插件。

协议

MIT License（与原 mod 不同）。原 mod 的代码未被直接复制，所有逻辑均为独立实现，规避 GPL-3.0 传染。

完整功能

🪄 法杖系统（5 级）

• 木法杖 (Lv1) / 铁法杖 (Lv2) / 金法杖 (Lv3) / 钻石法杖 (Lv4) / 下界合金法杖 (Lv5)
• 内置法术 + 滚轮切换（修 v1.0 timing bug）
• 5 级法杖槽位递增（1 → 12）

🔮 法术系统（13 种，对应 UsefulMagic 14 个法术中的 12 + 1 base）

ID	法术	等级	蓝耗	伤害	蓄力	CD	类别
base	基础	1	5	1	20	10	测试
sword_qi	剑气	1	15	8	30	40	攻击
charging	蓄力击	1	10	6	20	30	攻击
health	治疗	1	20	0	40	100	治疗
barrage	弹幕	2	20	5	40	60	攻击
golden	点金术	2	30	0	60	200	工具
lightning	闪电	3	40	15	60	100	攻击
light_beam	光束	3	25	12	30	30	攻击
sword_formation	剑阵	3	50	6	60	120	持续
meteorite	陨石	4	80	25	100	200	攻击
starry	星空	4	60	8	80	160	持续
anti_entity_domain	反领域	4	70	3	80	180	持续
explosion	爆破	5	150	30	120	240	攻击

💧 法力系统

• 默认 100 上限，每 tick +1
• 7 种金属块加成（参考 UsefulMagic V1.0 设计）
• ActionBar HUD 实时显示蓝条
• JSON 编码 PDC 持久化（已学法术 / 法力值跨服存续）

🌀 阵法系统（4 种阵法）

核心方块	阵法	效果	半径	耗蓝/tick
铁块	防御阵	友方 +0.2 吸收/tick	8	2
钻石块	恢复阵	生物 +0.3 HP/tick	8	1
绿宝石块	能量阵	主人 +2 mana/tick	6	3
红石块	剑阵	敌人 4 伤害/10tick	12	5

激活：手持法杖右键 末影水晶（周围 5 格内至少 1 个，最多 4 个）

🕯️ 祭坛系统

• 结构：附魔台/金块 + 周围 4+ 金块（5×3×5 范围）
• 操作：右键附魔台 → 打开 GUI（学习法术）
• 消耗：学习消耗 法术等级 × 20 法力

🔥 伤害系统

• Paper 1.21+ DamageSource API（DamageType.MAGIC）
• 命名空间魔法伤害，与原版伤害管线解耦

📜 命令

命令	描述	权限
/magic list	列出所有 13 个法术	magic.use
/magic reload	重载配置	magic.use
/wand <player> <type>	给玩家法杖	magic.admin
/spell list	列出你的已学法术	magic.use
/spell learn <id>	学习法术（无需祭坛）	magic.use
/spell info <id>	查看法术详情	magic.use

代码质量

指标	值
Java 文件	43
代码行数	2069
JAR 大小	83.1 KB
严重 bug	0
编译	✅ BUILD SUCCESS

架构亮点

1. 依赖注入（不再用 getInstance()）

• SpellServices record — 服务容器（mana / barrage / damage / store）
• AbstractSpell 抽象基类 — 提供 svc() 访问服务
• 13 个 Spell 全部通过 setup() 方法注入
• 可单元测试（不再依赖静态 instance）

2. 持续型法术

• SwordFormationSpell — 60 tick 持续（不再是单次判定）
• AntiEntityDomainSpell — 100 tick 持续 + 在线状态检查
• StarrySpell — 60 tick 持续 + 在线状态检查

3. JSON 持久化

• PlayerDataStore 用 JSON 数组 ["a","b","c"] 编码
• 支持任意字符的 spell ID（防 SQL/XSS-like 注入）

4. 命名空间伤害

• Paper 1.21+ DamageSource.builder(DamageType.MAGIC)
• 与 MOB_ATTACK / MELTING 等原版伤害区分

5. 修复的历史问题

• ✅ ManaManager 浮点扣蓝（(int) Math.ceil(cost)）
• ✅ 持续法术玩家退出 NPE（在线状态检查）
• ✅ GoldenSpell 附魔物品保留（拒绝附魔 + 保留 displayName）
• ✅ 滚动轮切法术时序 bug（前槽位判断）

文件结构（43 Java / 2069 行）

io.nahida.magic/
├── MagicPlugin.java              # 主类
├── api/                          # 核心 API（5 文件）
│   ├── Spell.java                # 接口
│   ├── AbstractSpell.java        # 抽象基类（带 services 注入）
│   ├── SpellServices.java        # 服务容器
│   ├── SpellProperty.java        # 分类枚举
│   └── SpellRegistry.java        # 注册表
├── spell/impl/                   # 13 个法术实现
│   ├── BaseMagicSpell.java
│   ├── SwordQiSpell.java         # 剑气
│   ├── ChargingSpell.java        # 蓄力击
│   ├── HealthSpell.java          # 治疗
│   ├── BarrageSpell.java         # 弹幕
│   ├── GoldenSpell.java          # 点金（限制附魔）
│   ├── LightningSpell.java       # 闪电
│   ├── LightBeamSpell.java       # 光束
│   ├── SwordFormationSpell.java  # 剑阵（持续）
│   ├── MeteoriteSpell.java       # 陨石
│   ├── StarrySpell.java          # 星空（持续）
│   ├── AntiEntityDomainSpell.java # 反领域（持续）
│   └── ExplosionSpell.java       # 爆破
├── wand/                         # 法杖（2 文件）
├── barrage/                      # 弹幕（4 文件）
├── mana/                         # 法力（2 文件）
├── formation/                    # 阵法（6 文件）
├── altar/                        # 祭坛（2 文件）
├── damage/                       # 伤害（1 文件）
├── listener/                     # 事件监听（3 文件）
├── command/                      # 命令（3 文件）
└── storage/                      # 数据存储（1 文件）

构建

cd Magic3
mvn package -DskipTests

输出：target/Magic3-3.0.0.jar

部署

详见 docs/DEPLOY.md

快速开始：

1. 复制 target/Magic3-3.0.0.jar 到服务器 plugins/ 目录
2. 重启 Paper 1.21+ 服务器
3. 测试命令：/wand <player> wood

文档

文档	内容
README.md	本文件
docs/DEPLOY.md	部署 + 验证 + 常见问题
docs/CONTRIBUTING.md	如何贡献（加法术、改阵法）
CHANGELOG.md	版本更新日志
review/Magic3-code-review.md	完整代码审查 + 三轮修复

致谢

• CooStack/UsefulMagic — 设计灵感来源（GPL-3.0）
• Paper — Minecraft 服务端 API

License

MIT License

Copyright (c) 2026 Renatus Madrigal

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND...