RepairShop
一款 Minecraft 插件,将 Citizens NPC 转化为铁匠。玩家右键点击该 NPC,菜单会列出他们携带的所有受损物品,每项单独定价,价格取决于磨损程度、材质以及附魔情况。支付通过 Vault 进行。
交互模式借鉴自 dtlTradersPlus:点击 NPC 获取商店窗口,但这里是用于修理而非交易。
玩家功能
右键点击铁匠 NPC。菜单会显示主背包、快捷栏、盔甲槽和副手槽中所有受损物品,并显示其剩余耐久度、价格和之前被修理过的次数。
- 修理一件物品:点击即可。
- 修理所有物品:一个按钮为所有物品计价。如果总价超出承受范围,它将优先修理最便宜的物品,从而让玩家用现有资金修复尽可能多的物品。
- 先查看价格:
/repairshop quote 对手中物品进行计价并显示完整明细;/repairshop prices 列出每种材质等级完全修理的费用。
没有固定费用。一把耐久度为 95% 的木斧最低收费为 2₽;而一把附魔且几乎报废的下界合金斧价格将超过 2,000₽。
管理员功能
- 多个商店。每个 NPC 指向一个带有独立标题、价格倍数、权限要求、接受的材质等级和拒绝的材质定义的商店配置。例如,村庄铁匠可以拒绝下界合金,而首都城市的顶级铁匠则以高价处理任何物品。
- 游戏内编辑器。使用
/repairshop shops 可以在图形界面中浏览、创建和编辑商店。它生成的 shops/<id>.yml 文件包含与手动编写文件相同的解释性注释。只有在按下“保存”后才会保存数据,且保存后的商店立即生效,无需重载。
- 等级折扣。基于权限的倍数折扣;玩家符合条件的最低倍数生效。
- 按商店的审计日志。每次付费修理都会追加记录到
shops/<id>/logs/<date>.log,格式为固定列、管道分隔的表格,便于 grep 搜索和导入电子表格。在第一次付费修理时创建,此前不存在。
- 完全可配置的文本。
messages.yml 中包含 179 个消息键,全部使用 MiniMessage 格式。缺失的键会回退到 jar 包中捆绑的副本,因此插件更新永远不会破坏已编辑的文件。
定价机制
完全由配置文件驱动,代码中没有硬编码的数字。每一项都是 config.yml 中的键值。
damageRatio = damage / maxDurability
baseValue = item-values[MATERIAL] OR tiers[TIER]
enchantAdd = SUM( enchantment value * level )
cost = (baseValue * typeMultiplier + enchantAdd)
* damageRatio ^ curve
* shopMultiplier
* rankDiscount
* workPenalty
cost = max(cost, minimum-cost)
**工作惩罚(work penalty)**是值得理解的术语。插件的修理完全绕过了原版铁砧的“过于昂贵”限制,否则附魔装备将永久耐用。因此,插件对该物品执行的每一次修理都会增加复合附加费,每次 +15%,最高上限为 4 倍。此计数存储在物品本身之上。
支持的平台
该插件完全不使用 NMS 或 CraftBukkit 内部实现,仅基于 Bukkit API 底层。这正是它能够在各个分支间移植的原因:因为没有服务器内部实现可供分支更改。
| 平台 |
支持情况 |
| Paper |
完全支持。这是在此开发、调优和启动测试的原生目标平台。 |
| Purpur, Pufferfish, Leaf 及其他 Paper 分支 |
完全支持。它们保留了完整的 Paper API。 |
| Spigot |
功能完整,但有两项自动降级,见下文。 |
| CraftBukkit |
与 Spigot 相同。 |
| Mohist, Arclight, CatServer, Ketting (Forge/Fabric 混合端) |
应该可以使用——它们实现了 Bukkit API,且本插件未触及低于该 API 的部分。未经测试,且混合端通常更不稳定。 |
在 Spigot 和 CraftBukkit 上,有两项内容处理方式不同。这两者在启动时自动检测,无需配置:
- 文本 Spigot 从未提供 Adventure 库,因此 MiniMessage 通过内置的传统
§ 翻译器渲染。颜色、十六进制色值和五种装饰样式均保留;渐变折叠为其第一个颜色,悬停/点击文本被丢弃但保留其内容。
- 聊天提示 使用
AsyncPlayerChatEvent 替代 Paper 的 AsyncChatEvent。
运行 /repairshop compat 可查看当前服务器采用了哪种路径。
不支持
- Folia Folia 的区域化线程移除了
Bukkit.getScheduler(),而本插件使用它来处理聊天提示超时、重新打开菜单和异步日志写入。此外,Folia 拒绝加载未声明 folia-supported: true 的插件,因此它会干净地失败而不是行为异常。要支持它,需要将这些调用站点移植到 Folia 的调度器,并审查“所有操作都在主线程上运行”这一修理流程所依赖的假设。
- BungeeCord / Velocity 代理服务器,而非 Bukkit 服务器。
- Vanilla、Forge 或 Fabric(无 Bukkit 桥接) 完全没有 Bukkit API。
支持的 Minecraft 版本
一个 JAR 文件支持 Minecraft 1.9 至 26.2。 插件在启动时通过检测服务器中已迁移的 API 的具体版本来确定兼容性,其判断依据始终是某个类或方法_是否存在_,而不是解析版本号字符串。这一点至关重要,因为 Minecraft 在 2026 年转向了基于年份的版本命名体系,因此将 1.21 与 26.2 进行比较是完全错误的。
api-version 固定为 1.13:这是现代服务器接受的最旧值,而 1.9–1.12 版本的服务器完全忽略该键。结合编译为 Java 8 字节码,这使得单个 JAR 文件能够覆盖整个版本范围。
在较旧服务器上的变化:
|
完整版本支持 |
其他情况 |
| MiniMessage 渐变、悬停提示、点击事件 |
Paper 1.16.5+ |
使用传统的 § 代码;颜色和装饰效果依然保留 |
| 工作惩罚 |
1.14+ |
不生效。 它需要持久化数据容器来存储每件物品的修理计数;在 1.14 以下版本中没有地方可以保存这个计数,因此每次修理都被视为首次修理。控制台会在启动时打印一次说明。 |
| 每件物品的最大耐久度 |
1.20.5+ |
使用该材质的默认值,这也是这些旧版本唯一可用的答案 |
| 附魔闪烁按钮 |
1.20.5+ |
使用较旧的隐藏附魔技巧。外观完全相同。 |
shops/*.yml 中的注释 |
1.18.1+ |
数值相同,保留标题,省略每行键的注释 |
| 超过 32 个字符的 GUI 标题 |
1.13+ |
截断以适应宽度,绝不会在颜色代码中间截断 |
材质和附魔名称的处理方式是“适配”而非“降级”:配置文件会同时读取扁平化之前和之后的词汇表,因此一个文件可以将 GOLDEN_AXE 和 GOLD_AXE,或者 DIG_SPEED 和 efficiency 视为同一事物进行定价。
要求
|
|
| 服务器 |
Minecraft 1.9 – 26.2,任何 Bukkit-API 实现(见上文) |
| Java |
取决于你的服务器本身所需的版本。该 JAR 文件是 Java 8 字节码,所有后续的 JVM 都能加载,因此它自身不增加任何额外要求 |
| 必需依赖 |
Vault 以及任意经济提供商(EssentialsX 是经过测试的) |
| 可选依赖 |
Citizens 如果没有它,NPC 功能不可用,但 /repairshop open 仍然可用 |
如果没有注册任何 Vault 经济提供商,插件会记录错误并禁用自身,因为它没有任何方式来收取费用。
命令与权限
/repairshop,别名 /rshop 和 /repairnpc。
| Command |
功能 |
权限 |
/repairshop help |
帮助页面,仅显示发送者可以运行的命令 |
|
/repairshop quote [shop] |
查看手中物品的价格,并提供详细分解 |
repairshop.quote (默认: true) |
/repairshop prices |
查看每种材质等级全额修理的费用 |
repairshop.quote (默认: true) |
/repairshop shops |
浏览、创建和编辑图形界面中的商店 |
repairshop.admin (默认: op) |
/repairshop create|edit|delete <shop> |
管理单个商店 |
repairshop.admin |
/repairshop assign <shop> / unassign |
将选定的 NPC 设置为修理商店,或取消此设置 |
repairshop.admin |
/repairshop open [shop] [player] |
打开商店菜单 |
repairshop.admin |
/repairshop list |
列出已配置的商店 |
repairshop.admin |
/repairshop compat |
显示本服务器的 API 差异是如何解决的 |
repairshop.admin |
/repairshop reload |
重新加载配置、消息和商店 |
repairshop.admin |
开启由 NPC 经营的商店需要 repairshop.use 权限 (默认:true)。
EssentialsX 拥有 /repair(以及 fix、efix、erepair),而 RepairShop 故意不占用该命令。
设置
将 Vault、一个经济插件提供者、Citizens 和 RepairShop-<version>.jar 放入 plugins/ 目录,启动服务器,然后执行:
/npc create Blacksmith
/repairshop assign default
这就是全部的设置步骤。
有关版本发布历史,请参阅 CHANGELOG.md。项目主页位于
C:\Coding\Java\Repair Shop Plugin,包含完整的文档集
docs/PRICING.md、docs/CONFIGURATION.md、docs/ARCHITECTURE.md、docs/BUILDING.md 和 docs/COMPATIBILITY.md。
RepairShop
A Minecraft plugin that turns a Citizens NPC into a blacksmith. Players right-click the NPC and a
menu lists every damaged item they are carrying, each priced individually on how worn it is,
what it is made of, and what is enchanted on it. Payment goes through Vault.
The interaction model is borrowed from dtlTradersPlus click an NPC, get a shop window but for
repairs instead of trades.
What players do
Right-click a blacksmith NPC. The menu shows every damaged item across their main inventory,
hotbar, armour slots and offhand, with its remaining durability, its price, and how many times it
has been repaired before.
- Repair one item click it.
- Repair everything one button prices the lot. If they cannot afford the total, it repairs
cheapest-first, so they get the largest number of items fixed for the money they have.
- Check a price first
/repairshop quote prices the item in hand and shows the full
breakdown; /repairshop prices lists the cost of a full repair for every material tier.
Nothing is a flat fee. A wooden axe at 95% durability costs the 2₽ minimum; the same axe in
netherite, enchanted and nearly broken runs past 2,000₽.
What admins get
- Multiple shops. Each NPC points at a shop definition with its own title, price multiplier,
permission, accepted tiers and refused materials so a village smith can turn away netherite
while a capital-city master smith handles anything at a premium.
- An in-game editor.
/repairshop shops browses, creates and edits shops in a GUI. It writes
shops/<id>.yml with the same explanatory comments a hand-written file has. Nothing is saved
until Save is pressed, and a saved shop is live immediately with no reload.
- Rank discounts. Permission-driven multipliers; the cheapest one a player qualifies for wins.
- Per-shop audit logs. Every paid repair appends to
shops/<id>/logs/<date>.log as a
fixed-column, pipe-separated table greppable and spreadsheet-friendly. Created by the first
paid repair, never before.
- Fully configurable text. 179 message keys in
messages.yml, all MiniMessage. Missing keys
fall back to the copy bundled in the jar, so a plugin update never breaks an edited file.
How pricing works
Entirely config-driven no numbers are baked into the code. Every term is a key in config.yml.
damageRatio = damage / maxDurability
baseValue = item-values[MATERIAL] OR tiers[TIER]
enchantAdd = SUM( enchantment value * level )
cost = (baseValue * typeMultiplier + enchantAdd)
* damageRatio ^ curve
* shopMultiplier
* rankDiscount
* workPenalty
cost = max(cost, minimum-cost)
The work penalty is the term worth understanding. Plugin repairs bypass vanilla's anvil
"Too Expensive" cap entirely, which would let enchanted gear last forever so every repair the
plugin has already performed on an item adds a compounding surcharge, +15% per repair, capped at
4×. The count is stored on the item itself.
Supported platforms
The plugin uses no NMS and no CraftBukkit internals at all nothing below the Bukkit API. That
is what makes it portable across forks: there are no server internals for a fork to change out
from under it.
| Platform |
Support |
| Paper |
Full. The native target developed, tuned and boot-tested here. |
| Purpur, Pufferfish, Leaf and other Paper forks |
Full. They keep the entire Paper API. |
| Spigot |
Full features, with two automatic downgrades see below. |
| CraftBukkit |
Same as Spigot. |
| Mohist, Arclight, CatServer, Ketting (Forge/Fabric hybrids) |
Should work they implement the Bukkit API, and nothing here reaches below it. Untested, and hybrids are flakier in general. |
On Spigot and CraftBukkit two things resolve differently. Both are detected at startup and need
no configuration:
- Text Spigot has never shipped Adventure, so MiniMessage is rendered through the built-in
legacy
§ translator instead. Colours, hex and the five decorations all survive; gradients
collapse to their first colour, and hover/click text is dropped while keeping its contents.
- Chat prompts
AsyncPlayerChatEvent is used instead of Paper's AsyncChatEvent.
/repairshop compat reports which route the running server took.
Not supported
- Folia Folia's regionised threading removes
Bukkit.getScheduler(), which this plugin uses
for chat-prompt timeouts, reopening menus and async log writes. Folia also refuses to load
plugins that do not declare folia-supported: true, so it fails cleanly rather than
misbehaving. Supporting it would mean porting those call sites to Folia's schedulers and
auditing the "everything runs on the main thread" assumption the repair flow is built on.
- BungeeCord / Velocity proxies, not Bukkit servers.
- Vanilla, Forge or Fabric without a Bukkit bridge no Bukkit API at all.
Supported Minecraft versions
One jar runs on Minecraft 1.9 through 26.2. The plugin works out at startup which flavour of
each moved-around API the server has, always by asking whether a class or method exists rather
than by parsing a version string which matters, because Minecraft moved to year-based versioning
in 2026, so comparing 1.21 against 26.2 is actively wrong.
api-version is pinned at 1.13: the oldest value any modern server accepts, and a key that
1.9–1.12 ignore entirely. That, plus compiling to Java 8 bytecode, is what lets a single jar cover
the whole range.
What changes on older servers:
|
Full version |
Elsewhere |
| MiniMessage gradients, hover, click |
Paper 1.16.5+ |
Legacy § codes; colours and decorations survive |
| The work penalty |
1.14+ |
Inactive. It needs the persistent data container to store a per-item repair count; below 1.14 there is nowhere to keep one, so every repair is priced as a first repair. The console says so once at startup. |
| Per-item max durability |
1.20.5+ |
The material's value is used, which is the only answer those versions have |
| Enchanted-glint buttons |
1.20.5+ |
The older hidden-enchantment trick. Looks identical. |
Comments in shops/*.yml |
1.18.1+ |
Same values, header kept, per-key notes omitted |
| GUI titles over 32 characters |
1.13+ |
Trimmed to fit, never mid-colour-code |
Material and enchantment names are handled rather than degraded: config files are read in both the
pre- and post-flattening vocabularies, so one file prices GOLDEN_AXE and GOLD_AXE, or
DIG_SPEED and efficiency, as the same thing.
Requirements
|
|
| Server |
Minecraft 1.9 – 26.2, on any Bukkit-API implementation (see above) |
| Java |
Whatever your server already needs the jar is Java 8 bytecode, which every later JVM loads, so it adds no requirement of its own |
| Required |
Vault plus any economy provider (EssentialsX is the tested one) |
| Optional |
Citizens without it the NPC trait is unavailable and /repairshop open still works |
If no Vault economy provider is registered, the plugin logs an error and disables itself, since it
has no way to charge for anything.
Commands and permissions
/repairshop, aliases /rshop and /repairnpc.
| Command |
Does |
Permission |
/repairshop help |
Help page, showing only what the sender may run |
|
/repairshop quote [shop] |
Price the item in hand, with the full breakdown |
repairshop.quote (default: true) |
/repairshop prices |
Cost of a full repair for every material tier |
repairshop.quote (default: true) |
/repairshop shops |
Browse, create and edit shops in a GUI |
repairshop.admin (default: op) |
/repairshop create|edit|delete <shop> |
Manage one shop |
repairshop.admin |
/repairshop assign <shop> / unassign |
Turn the selected NPC into a repair shop, or stop it being one |
repairshop.admin |
/repairshop open [shop] [player] |
Open a shop menu |
repairshop.admin |
/repairshop list |
List the configured shops |
repairshop.admin |
/repairshop compat |
Show how this server's API differences were resolved |
repairshop.admin |
/repairshop reload |
Reload config, messages and shops |
repairshop.admin |
Opening a shop from an NPC needs repairshop.use (default: true).
EssentialsX owns /repair (plus fix, efix, erepair), and RepairShop deliberately does not
claim it.
Setup
Drop Vault, an economy provider, Citizens and RepairShop-<version>.jar into plugins/, start
the server, then:
/npc create Blacksmith
/repairshop assign default
That is the whole setup.
See CHANGELOG.md for release history. The project home at
C:\Coding\Java\Repair Shop Plugin carries the full documentation set
docs/PRICING.md, docs/CONFIGURATION.md, docs/ARCHITECTURE.md, docs/BUILDING.md and
docs/COMPATIBILITY.md.
评论 0
登录后参与评分
还没有评论,来抢沙发吧