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

Firing Item Demo

Creating Item Demo

---

Credits

Built on Paper and triumph-gui (MIT, © 2021 TriumphTeam), which powers the in-game creator GUI and is bundled inside the jar.