ItemSmith
Paper 平台的自定义物品:一套能力引擎与真正的游戏内物品创建器。
给剑附加中毒攻击。制作一把击中目标后冻结它的斧头。打造一把能矿脉挖掘并自动熔炼的镐子,一把能穿过墙壁瞬移的法杖,以及一个能治愈附近所有人的图腾。然后通过合成、怪物掉落、钓鱼收获或箱子获取这些物品,让你的玩家能在原版配方书中发现它们。
你可以在游戏内通过箱子 GUI 构建所有这些内容,也可以手动编辑一个小型且易读的 YAML 文件。两种方式写入的是同一个文件。执行 /reload 命令即可即时生效。
预发布版本。 ItemSmith 正处于最终上线前的打磨阶段。本页面描述的是基于 Paper 1.21.8 构建和测试的插件状态;它尚未作为公开版本发布。
引擎工作原理
每个物品由 基础材质 + 显示文本 + 一组能力列表 组成。每个 能力 都是一个小型管道:
触发器 (何时) → 条件 (如果) → 目标选择器 (对谁) → 动作 (做什么),并可选地包含一个 门控/限制 (是否允许?)。
- 触发器 (Activator):触发时机。命中时、右键点击时、击杀时、潜行时、受到跌落伤害时、破坏方块时、手持时每刻……
- 条件 (Conditions):通过/失败检查。仅在此世界中、生命值低于 30% 时、仅在夜间、仅当目标是玩家时……
- 目标选择器 (Targeter):动作作用的对象。你击中的实体、你自己、一定半径内的所有实体、你注视的方块、投射物……
- 动作 (Actions):发生的行为。造成伤害、施加效果、击退目标、破坏一片区域的方块、传送、生成实体、播放声音……
由于每个组件都声明了自己的类型化参数,GUI 可以自动为其渲染编辑器,YAML 序列化程序也可以自动读取和写入数据。这就是 ItemSmith 在不为每个功能单独构建菜单的情况下达到这种规模的原因:
| 组件 |
数量 |
示例 |
| 触发器 |
~150 |
左键/右键点击、被击中/击中、击杀、死亡、破坏/放置方块、消耗、潜行、丢弃/拾取、投射物、装备、手持每刻 |
| 动作 |
~160 |
伤害、药水效果、击退、拉扯、生命窃取、点燃、冻结、传送/闪烁/冲刺、区域破坏、矿脉破坏、自动熔炼、生成实体、给予物品、经济系统 |
| 条件 |
~70 |
生命值/饥饿值、世界、区域、时间、物品、目标类型、充能次数、冷却时间、余额、权限 |
| 目标选择器 |
18 |
自身、目标、附近实体、注视的方块、区域、视线方向 |
总计约 400 个注册的引擎组件。 插件在启动时会记录确切数量。
流程控制(分支能力)
动作不仅仅是一个扁平列表;其中几个是嵌套的流程控制块,因此一个能力可以进行决策并按顺序执行自身逻辑:
- delay:等待,然后继续
- repeat:将子列表运行 N 次
- if:仅当条件满足时运行子列表
- random / chance:选择一个分支,或者仅在部分时间内触发
- abort:提前停止该能力
将它们组合起来,单个能力就可以随时间错开效果、随机判定暴击,或展开连招,无需编写代码,只需使用嵌套块即可。
门控与经济系统(平衡你的物品)
每个能力都可以设置门控,使力量需要付出代价:
- 权限 (Permission):限制谁能触发它。
- 世界/区域 (World / region):限制在哪里使用(通过 WorldGuard 进行区域门控,可选)。
- 通过 Vault 的使用成本 (Use-cost via Vault):每次激活时收取金钱、经验值、物品或饥饿值。
- 充能次数与自定义耐久度:有限使用次数的物品,耗尽后会损坏。
- 冷却组 (Cooldown groups):在多个能力间共享一个冷却时间,或为每个能力设置独立的冷却时间。
(管理员 itemsmith.bypass.* 权限允许工作人员跳过成本、冷却时间或区域门控以进行测试。)
获取方式:将物品放入世界的经济系统中
无法获得的物品只是一张截图。ItemSmith 通过所有 Bukkit 原生途径使自定义物品可获取:
- 全原生系列的配方:形状、无形状、熔炉/blast/smoking/campfire、锻造台转换、切石机。每个物品可有多个配方,并且它们会显示在原版配方书中。
- 怪物与方块掉落:按几率和数量掉落,可选择仅限玩家击杀,并对方块处理精准采集。
- 战利品表注入 (Loot-table injection):将物品注入箱子、怪物和钓鱼的战利品表中。
- 玩家目录 GUI:一个可浏览、可搜索的游戏内目录(受
itemsmith.catalog 权限保护,默认授予),玩家可以在其中查看所有自定义物品、每种物品的获取方式,并将已知的配方添加到自己的配方书中。
游戏内创建器
一个仅限管理员使用的箱子 GUI 创建器,基于 triumph-gui 和原生 Paper 对话框 API 构建,因此文本输入、搜索框和确认提示看起来像原版风格,本身不需要资源包:
- 从模板(武器/工具/护甲/消耗品/穿戴品)或空白物品开始。
- 编辑 id、材质、名称、描述、冷却时间、物品设置、配方、掉落、战利品以及完整的能力树,包括深入嵌套的流程控制块。
- 从带分类文件夹和搜索功能的选项中选择触发器、条件、目标选择器和动作,无需记忆名称。
- 简单 + 高级 的渐进式披露保持常用路径简短。
- 不可变 id + 另存为 保护现有物品;编辑操作写入相同的 YAML 并实时重载。
- 内置的 配方/掉落/战利品编辑器 和 管理员给予 功能完善了整个体验。
GUI 所做的所有事情,你也可以在 YAML 中手动完成;它们是通往同一个文件的两个入口。
最小化示例物品
plugins/ItemSmith/items/venom_blade.yml:
material: DIAMOND_SWORD
name: "<gradient:#00e676:#1de9b6>Venom Blade</gradient>"
lore:
- "<dark_gray>Coated in a lethal toxin.</dark_gray>"
- "<gray>On hit: <green>Poison</green> + bonus damage</gray>"
能力:
- activator: player_hit_entity # 当你近战击中目标时
targeter: target # 作用于你击中的实体
cooldown: 1.5 # 秒;显示原版冷却扫掠动画
actions:
- type: add_damage # 击中时增加额外伤害
amount: 2 # 2.0 = 一颗心(半颗血)
- type: potion_effect # 然后给目标施加中毒效果
effect: poison
duration: 5 # 秒
amplifier: 0 # 0 = I 级
配方:
type: shaped
shape:
- " F "
- " D "
- " S "
ingredients:
F: FERMENTED_SPIDER_EYE
D: DIAMOND
S: STICK
将该文件放入插件目录,运行 /itemsmith reload,然后执行 /itemsmith get venom_blade。或者在 GUI 中构建完全相同的内容,它会自动为你生成此文件。分享该文件后,其他服务器的管理员也可以导入并使用该项目。
纹理:自带资源包(目前)
ItemSmith 尚不自动生成资源包。自定义纹理和模型需自带资源包:将物品指向 item-model: 或 custom-model-data: 并提供你自己的资源包即可渲染。开箱即用状态下,物品使用其基础材质的外观,且 GUI 采用原生样式,因此无需任何资源包。自动生成资源包的功能已在路线图规划中(见下文)。
要求与兼容性
- 服务端: Paper 1.21.8。ItemSmith 仅使用 Paper 专属 API(Adventure/MiniMessage 文本、原生 Dialog API),因此不支持 Spigot。
- Java: 21+。
- 安装: 将单个 jar 文件放入
/plugins 目录并重启服务器。GUI 库已阴影化并重定位至 jar 内部,无需额外安装任何东西。
- 可选软依赖(缺失时优雅降级): Vault(经济费用)、WorldGuard(区域限制)、GriefPrevention(保护机制)。
- 客户端: 这是一个服务端插件,因此玩家无需安装任何东西。管理员创建者使用原生 Dialog API 进行文本和数字输入,这需要 1.21.6+ 版本的客户端;在较旧客户端上会显示明确提示消息,而非静默失败。
- Folia: 尚未确认支持。
命令与权限
命令 /itemsmith(别名 /ismith, /citems):
| 子命令 |
功能 |
catalog |
打开玩家目录(浏览 / 搜索 / 获取方式) |
open |
打开管理员创建器 GUI |
create |
开始创建一个新物品 |
get <id> |
给自己一个自定义物品 |
give <id> [player] |
将一个自定义物品给予某玩家 |
list |
列出所有已定义的物品 |
reload |
从磁盘重新加载物品文件 |
权限节点:
| 节点 |
默认值 |
用途 |
itemsmith.admin |
op |
创建器 GUI + 所有管理员命令 |
itemsmith.catalog |
true |
打开玩家目录 |
itemsmith.bypass.all |
false |
绕过所有能力门禁 |
itemsmith.bypass.cost |
false |
绕过使用费用 |
itemsmith.bypass.cooldown |
false |
绕过冷却组 |
itemsmith.bypass.region |
false |
绕过区域限制 |
路线图
目前已构建并正常运行:完整的能力引擎、约 150 个触发器 / 约 160 个动作 / 约 70 个条件 / 18 个目标选择器、嵌套流程控制、门禁与经济系统、游戏内创建器 GUI、所有 Bukkit 原生配方、生物/方块掉落、战利品表注入、玩家目录及配方书集成。
计划中(尚未加入插件,列出以便你了解即将推出的功能,并非暗示当前可用):
- 资源包生成:自动自定义纹理/模型(目前需自带资源包)。
- PlaceholderAPI 占位符及更深入的 MythicMobs 集成。
- 本地化(可翻译的消息)。
- 导入 / 导出物品文件。
- 自定义方块与生物(发布后)。
TL;DR(太长不看版)
适用于 Paper 1.21.8 的自定义物品插件,采用基于模式的引擎(触发器 → 条件 → 目标选择器 → 动作),包含约 400 种组件、嵌套流程控制、费用/冷却/区域门禁、所有原生配方类型以及掉落和战利品注入、游戏内箱子式 GUI 创建器,以及玩家目录。物品以可共享的 YAML 格式存储。自定义纹理需自带资源包。
演示视频
致谢
基于 Paper 和 triumph-gui(MIT 协议,© 2021 TriumphTeam)构建,后者为游戏内创建器 GUI 提供动力,并已打包进本 jar 文件中。
ItemSmith
Custom items for Paper: an ability engine and a real in-game item creator.
Give a sword a poison strike. Make an axe that freezes what it hits. Build a pickaxe that vein-mines and auto-smelts, a wand that blinks you through walls, a totem that heals everyone nearby. Then hand the item to your players through a craft, a mob drop, a fishing catch, or a chest, and let them discover it in the vanilla recipe book.
You build all of it in-game, through a chest GUI, or by hand-editing a small, readable YAML file. Both write the same file. Both /reload instantly.
Pre-release. ItemSmith is in final pre-launch polish. This page describes the plugin as built and tested on Paper 1.21.8; it is not yet a public release.
How the engine works
Every item is a base material + display text + a list of abilities. Each ability is a small pipeline:
Activator (when) → Conditions (if) → Targeter (who) → Actions (what), with an optional Gate (may I?).
- Activator: the trigger. On hit, on right-click, on kill, on sneak, on take-fall-damage, on block break, every tick while held…
- Conditions: pass/fail checks. Only in this world, only below 30% health, only if it's night, only if the target is a player…
- Targeter: who the actions run on. The entity you hit, yourself, everyone in a radius, the block you're looking at, a projectile…
- Actions: what happens. Deal damage, apply an effect, launch the target, break an area of blocks, teleport, spawn an entity, play a sound…
Because every component declares its own typed parameters, the GUI can render an editor for it automatically and the YAML serializer can read/write it automatically. That's how ItemSmith reaches this scale without hand-building a menu per feature:
| Component |
Count |
Examples |
| Activators |
~150 |
right/left click, hit/be-hit, kill, death, block break/place, consume, sneak, drop/pickup, projectile, equip, hold-tick |
| Actions |
~160 |
damage, potion effect, knockback, pull, lifesteal, ignite, freeze, teleport/blink/dash, area-break, vein-break, auto-smelt, spawn entity, give item, economy |
| Conditions |
~70 |
health/hunger, world, region, time, item, target type, charges, cooldown, balance, permission |
| Targeters |
18 |
self, target, nearby entities, looked-at block, area, look direction |
≈400 registered engine components in total. The plugin logs the exact count on boot.
Flow control (abilities that branch)
Actions aren't just a flat list; several are nested flow-control blocks, so an ability can make decisions and sequence itself:
- delay: wait, then continue
- repeat: run a sub-list N times
- if: run a sub-list only when a condition holds
- random / chance: pick a branch, or fire only some of the time
- abort: stop the ability early
Combine them and a single ability can stagger effects over time, roll for a critical, or fan out a combo, with no code and just nested blocks.
Gating & economy (balance your items)
Every ability can be gated so power costs something:
- Permission: restrict who can trigger it.
- World / region: restrict where (region gating via WorldGuard, optional).
- Use-cost via Vault: charge money, XP, items, or hunger per activation.
- Charges & custom durability: limited-use items that deplete and can break.
- Cooldown groups: share one cooldown across several abilities, or give each its own.
(Admin itemsmith.bypass.* permissions let staff skip cost, cooldown, or region gates for testing.)
Obtaining: put items into the world's economy
An item nobody can get is just a screenshot. ItemSmith makes custom items reachable through every Bukkit-native path:
- Recipes across all native families: shaped, shapeless, furnace / blasting / smoking / campfire, smithing transform, and stonecutter. Multiple recipes per item, and they show up in the vanilla recipe book.
- Mob & block drops: by chance and count, optionally player-kill-only, with silk-touch handling for blocks.
- Loot-table injection: inject items into chest, mob, and fishing loot tables.
- Player catalog GUI: a browsable, searchable in-game catalog (behind
itemsmith.catalog, granted by default) where players see every custom item, how to obtain each one, and can add known recipes to their recipe book.
The in-game creator
An admin-only chest-GUI creator, built on triumph-gui and the native Paper Dialog API, so text entry, search boxes and confirmations look like vanilla, with no resource pack required for the GUI itself:
- Start from a template (Weapon / Tool / Armor / Consumable / Wearable) or a blank item.
- Edit id, material, name, lore, cooldown, item settings, recipe, drops, loot, and the full ability tree, including drilling into nested flow-control blocks.
- Pick activators, conditions, targeters and actions from categorized folders with search, so there are no names to memorize.
- Simple + Advanced progressive disclosure keeps the common path short.
- Immutable ids + Save-As protect existing items; edits write the same YAML and reload live.
- In-GUI recipe / drops / loot editors and admin give round it out.
Everything the GUI does, you can also do by hand in YAML; they're two doors into the same file.
A minimal example item
plugins/ItemSmith/items/venom_blade.yml:
material: DIAMOND_SWORD
name: "<gradient:#00e676:#1de9b6>Venom Blade</gradient>"
lore:
- "<dark_gray>Coated in a lethal toxin.</dark_gray>"
- "<gray>On hit: <green>Poison</green> + bonus damage</gray>"
abilities:
- activator: player_hit_entity # when you hit something in melee
targeter: target # act on the entity you hit
cooldown: 1.5 # seconds; shows the vanilla cooldown sweep
actions:
- type: add_damage # extra damage on the hit
amount: 2 # 2.0 = one heart
- type: potion_effect # then poison the target
effect: poison
duration: 5 # seconds
amplifier: 0 # 0 = level I
recipe:
type: shaped
shape:
- " F "
- " D "
- " S "
ingredients:
F: FERMENTED_SPIDER_EYE
D: DIAMOND
S: STICK
Drop that file in, run /itemsmith reload, and /itemsmith get venom_blade. Or build the exact same thing in the GUI and it writes this file for you. Share the file and anyone else's server has the item.
Textures: Bring Your Own Pack (for now)
ItemSmith does not generate resource packs yet. Custom textures and models are Bring-Your-Own-Pack: point an item at item-model: or custom-model-data: and supply your own pack, and it renders. Out of the box, items use their base material's look, and the GUI is native-styled so it needs no pack at all. Automatic resource-pack generation is on the roadmap (see below).
Requirements & compatibility
- Server: Paper 1.21.8. ItemSmith uses Paper-only APIs (Adventure/MiniMessage text, the native Dialog API), so Spigot is not supported.
- Java: 21+.
- Install: drop the single jar into
/plugins and restart. The GUI library is shaded and relocated inside it, with nothing else to install.
- Optional soft-depends (graceful if absent): Vault (economy costs), WorldGuard (region gating), GriefPrevention (protection).
- Client: a server-side plugin, so players install nothing. The admin creator uses the native Dialog API for text and number entry, which needs a 1.21.6+ client; on older clients it shows a clear message rather than failing silently.
- Folia: not yet confirmed.
Commands & permissions
Commands for /itemsmith (aliases /ismith, /citems):
| Subcommand |
What it does |
catalog |
Open the player catalog (browse / search / how-to-obtain) |
open |
Open the admin creator GUI |
create |
Start a new item in the creator |
get <id> |
Give yourself a custom item |
give <id> [player] |
Give a custom item to a player |
list |
List all defined items |
reload |
Reload item files from disk |
Permissions:
| Node |
Default |
Purpose |
itemsmith.admin |
op |
Creator GUI + all admin commands |
itemsmith.catalog |
true |
Open the player catalog |
itemsmith.bypass.all |
false |
Bypass all ability gates |
itemsmith.bypass.cost |
false |
Bypass use-costs |
itemsmith.bypass.cooldown |
false |
Bypass cooldown groups |
itemsmith.bypass.region |
false |
Bypass region gating |
Roadmap
Built and working today: the full ability engine, ~150 activators / ~160 actions / ~70 conditions / 18 targeters, nested flow control, gating & economy, the in-game creator GUI, all Bukkit-native recipes, mob/block drops, loot-table injection, the player catalog and recipe-book integration.
Planned (not yet in the plugin, listed so you know what's coming, not implying it's here):
- Resource-pack generation: automatic custom textures/models (today it's BYO-pack).
- PlaceholderAPI placeholders and deeper MythicMobs integration.
- Localization (translatable messages).
- Import / export of item files.
- Custom blocks & mobs (post-launch).
TL;DR
A custom-items plugin for Paper 1.21.8 with a schema-driven ability engine (Activator → Conditions → Targeter → Actions), ~400 components, nested flow control, cost/cooldown/region gating, every native recipe type plus drops and loot injection, an in-game chest-GUI creator, and a player catalog. Items are shareable YAML. Bring your own resource pack for custom textures.
Demo Videos
Credits
Built on Paper and triumph-gui (MIT, © 2021 TriumphTeam), which powers the in-game creator GUI and is bundled inside the jar.
评论 0
登录后参与评分
还没有评论,来抢沙发吧