ItemSmith

# 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`: ```yaml material: DIAMOND_SWORD name: "Venom Blade" lore: - "Coated in a lethal toxin." - "On hit: Poison + bonus damage" 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 ` | Give yourself a custom item | | `give [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.