Page 4

SuperItems 3.0: Quick User Manual

A Paper plugin (Java 25, Paper 26.x) for creating custom items, armor, armor sets, mobs/minibosses/bosses, loot tables and spawners in game. No coding required.

1. Install

1. Build with ./gradlew build (or ./gradlew jar). The jar lands in build/libs/SuperItems-2.0.0.jar.
2. Drop it in your server's plugins/ folder, start the server, and you are done.
3. Permission: superitems.admin (ops by default). Aliases: /superitems, /sitems, /si.

2. The one rule that covers everything

Every command is: /superitems [group] <action> <id> --flag value --flag value

• A value runs until the next --flag, so it can contain spaces and whole commands.
• Flags can repeat (--effect ... --effect ...).
• On edit, use none to clear a flag: --on_hit none.
• Text accepts & color codes or MiniMessage (<green>, <#ff8800>).
• A command with a mistake changes nothing, and it tells you why.
• Press Tab for flag and value suggestions, or use the menus in section 3 instead of typing. Type a group name alone (/superitems mob) to list its commands.

Group	Actions
(items)	create edit delete give list info reload
armor	create edit delete give list info
set	create edit delete list info
mob	create edit delete list info spawn kill active
loot	create edit delete list info roll drop test
spawner	create edit delete list info

Build in this order, because commands check that referenced ids exist: items/armor, then sets and loot, then mobs, then spawners.

3. The menus (no commands needed)

Run /superitems gui (players only). Everything the commands can do is a click away, and the menus run the same create, edit and delete checks, so they can never save something the commands would refuse. Jump straight to a page with /superitems gui <items|armor|sets|mobs|loot|spawners|textures|pack|history|import|check>.

• Main menu: one button per kind (with counts), Texture studio, Resource pack, History, Import/Export, Check everything, Help, Reload.
• Lists: left click edits, right click is the quick action (get an item, spawn a mob, roll a table, teleport to a spawner), shift + left duplicates, shift + right deletes. Search, paging, New (guided: id, then the one or two settings that kind needs) and New from the item in my hand (items) are in the bottom row.
• Editor: tabs across the top (Look, Texture, Click, Combat, Worn, Stats for items; Identity, Stats, Gear, Triggers, Boss bar, Drops, Spawning for mobs; and so on). The top right button is a live preview with the real tooltip. Click a setting to change it:
  • text and numbers are typed in chat (type cancel to go back; a clickable line puts the current text in your chat box to edit); right click clears
  • on/off settings flip; fixed choices, materials (drop an item on the button to copy its material), entity types, colors, items, mobs and loot tables open searchable pickers
  • line settings (triggers, timers, phases, attributes, effects, loot entries) open the line editor: add, edit, remove, shift + click to reorder. Add from presets inserts ready made commands (effects, sounds, particles, titles, damage, lightning, dash, summon and more). Loot entries use a builder (kind, item, weight, amount, chance) and show each entry's share of a roll.
• Tools row: history, duplicate, export, check for problems, and per kind: give item, spawn or kill a mob, roll or simulate 1000 rolls of a table, and for spawners move here, show area (particles for the scatter radius and range) and a placement wand (right click a block to move the spawner above it).
• History and undo: every menu change saves the data files first (a burst of edits to one thing counts as one step). Click a version to restore it; your current state is saved first, so nothing is lost. history-limit in config.yml sets how many are kept.
• Import and export: Export to file writes plugins/SuperItems/exports/<kind>-<id>.yml, including the item's texture. Put such a file in plugins/SuperItems/imports on another server and click it in the Import menu. A taken id gets _2 added.
• Check everything: finds missing items, loot tables, mobs and riders, unwearable set pieces, loot tables that roll themselves, unloaded spawner worlds and models without textures. Click a finding to open it.

4. Items

/superitems create frog_stick --name &aFrog Stick --description &7big hopppps --material stick --glow
  --on_right_click effect give @p minecraft:jump_boost 3 3 true
  --on_left_click playsound minecraft:entity.frog.ambient master @p
  --cooldown 5 --consume right
/superitems give frog_stick [player] [amount]

• Click flags: --on_right_click, --on_left_click, --cooldown s, --consume none|right|left|both, --cancel true|false.
• Look: --name --description --material --model --glow --color #rrggbb (leather dye).
• Combat: --damage 400-600 rolls a random hit in that range (scaled by attack charge), --on_hit, --on_damaged, --trigger_cooldown s.
• Stats: --attribute "name amount [add|mult|mult_total] [slot]", --unbreakable. Setting any attribute replaces the base item's defaults, so list every stat you want.
• Worn/held: --on_equip, --on_unequip, --while_worn <cmd> --interval s (default 2 s).
• Placeholders: %target%, %targetname% (on_hit), %attacker% (on_damaged), %player%.

5. Armor and sets

/superitems armor create crown --piece helmet --tier netherite --name &6King's Crown --armor 4 --toughness 3 --health 6 --unbreakable
/superitems set create kings --pieces crown,plate --bonus 2 effect give @s minecraft:resistance 3 0 true --on_activate 2 title @s title "Set!"

• Armor: --piece helmet|chestplate|leggings|boots, --tier leather|chainmail|iron|golden|diamond|netherite|turtle, stats --armor --toughness --health --speed --kb_resist. For percent bonuses use --attribute "speed 0.15 mult".
• Sets: --bonus "<n> <command>" repeats while at least n pieces are worn (effects should outlast --interval). --on_activate / --on_deactivate fire once when the count is reached or lost.

6. Mobs, minibosses and bosses

/superitems mob create king --tier boss --type wither_skeleton --name &4&lSkeleton King
  --health 800 --damage 14 --speed 1.2x --scale 1.5 --mainhand blade --helmet crown
  --timer 12 summon minecraft:skeleton ~ ~ ~   --phase 50 effect give @s minecraft:speed infinite 2 true
  --loot king_loot --xp 300-500 --vanilla_drops false --announce server
/superitems mob spawn king [amount] [world x y z]

• Tiers: enemy, miniboss, boss. Tier only sets defaults (bosses get a boss bar and never despawn); any default can be overridden.
• Stats: a trailing x multiplies the vanilla value (1.5x).
• Gear: item/armor ids or vanilla materials; --equipment_drop percent.
• Abilities: --timer "seconds cmd" (while a player is within --active_range, default 64), --phase "percent cmd" (once, when health falls to that percent), --on_spawn --on_hit --on_damaged --on_death --on_kill.
• Boss bar: --bar_color --bar_style --bar_range --bar_title.
• Natural spawns: --replace zombie 10 swaps 10% of zombie spawns for this mob; --worlds a,b limits it.
• Mob commands run as the mob, so @s is the mob. Prefix target: to run as the involved player, player: for that player's permissions, raw: for console. on_death always runs from the console. Extras: %mob% %mobid% %x% %y% %z% %world% %killer%.
• mob kill [id] removes mobs without drops; mob active counts live ones.

7. Loot tables

/superitems loot create king_loot --rolls 1-2 --chance 100 --deliver drop
  --entry 50 vanilla:bone 5-12   --entry 10 item:blade   --entry 5 item:crown chance=50
  --entry 1 table:rare_gems      --entry 30 nothing      --always 1 vanilla:experience_bottle 3-6

• Entry = weight kind:ref [amount] [chance=%]. Kinds: item:, vanilla:, table: (nest tables), command:, nothing.
• --always entries roll every time. --deliver inventory sends mob loot straight to the killer.
• On edit, --entry adds; use --entry none --entry ... to replace.
• Tune with loot test <table> [times] (simulates, gives nothing), loot roll <table> [player], loot drop <table> [world x y z].

8. Spawners

/superitems spawner create crypt --mob king --here --interval 600 --max 1 --range 48

--here or --location x y z [world] (console must name the world), --interval seconds (default 30), --amount per wave (1-50), --max alive at once (1-500), --radius scatter, --range activation distance (0 = always), --enabled true|false.

9. Logic: run-as flags, variables and if checks

These work in every command list: item, armor, set, mob and NPC triggers, plus loot command: entries.

Who runs a line. Add one word anywhere in the line:

• --as_console (default): the console runs it as and at the player (for mobs: as the mob).
• --as_player: the player runs it with their own permissions. Use this when the command needs PlaceholderAPI or is a per player command such as spawn.
• --as_op: the player runs it as operator for that one command only, then OP is taken away again. Be careful: the line can do anything an operator can. Items, armor, sets, NPCs and loot tables also take --run_as console|player|op: the default for every line of that definition that has no word of its own (a word in the line always wins). Console stays the default. The older prefixes still work: player: is the same as --as_player, raw: runs from the console exactly as written, and target: (mobs) runs as the player involved. In the line editor, press Q on a line to switch between console, player and op.

Variables. var set|add|sub|del|toggle <variable> [value]

Variable	Belongs to	Saved?
var_global.name / var_global_temp.name	the whole server	yes / no (memory only)
var_account.name / var_account_temp.name	the player involved	yes / no
var_local.name / var_local_temp.name	the region the player stands in	yes / no
Pick an owner explicitly with var_account@Steve.name or var_local@spawn.name. Read a value in any line as %var_account.kills%. If PlaceholderAPI is installed, other plugins can show it as %superitems_var_account.kills%.
Regions are boxes of blocks: /superitems region create spawn --here --radius 10, or --pos1 / --pos2 where you stand, or --world w --from x y z --to x y z. When regions overlap, the smallest one counts.

If checks.

if var_account.kills >= 5 and has_item:ruby_sword then message &aWell done! else message &cKeep going
require has_item:diamond:3 else message &cYou need 3 diamonds
take diamond 3
var add var_account.purchases 1
wait 2
message &6Thanks, %player%!

• Compare with == != > >= < <= contains. Join parts with and / or, and flip one with not or !.
• Tests: has_item:<item>[:amount], holding:<item>, permission:<node>, region:<id>, world:<name>, chance:<percent>, op, sneaking.
• <item> is a SuperItems id or a vanilla material.
• require stops the remaining lines when it fails. stop ends the lines. wait <seconds> pauses before the next lines.
• Try a condition with /superitems var test <condition>.
• Look at and change variables in the menu (Variables) or with /superitems var get|set|add|sub|del|list|clear.

10. Recipes

/superitems recipe create ruby_sword --type shaped --result ruby_sword --grid air ruby air air ruby air air stick air
/superitems recipe create ruby_smelt --type furnace --input ruby_ore --result ruby --xp 1 --time 8

• Types: shaped, shapeless, furnace, blasting, smoking, campfire, stonecutting, smithing (--template --base --addition).
• Every ingredient and result can be a SuperItems item or a vanilla item.
• --grid lists 9 cells row by row, with air for an empty cell.
• In the menu, Recipes > Crafting grid: pick up an item on your cursor and click a cell. Your item is not used up.
• Recipes rebuild when an item changes, and they show up in players' recipe books.
• An unfinished recipe is kept but not active; Check everything says what is missing.

11. NPCs

An NPC is a set of click actions (the same lines as triggers, so if, var, wait and run-as all work).

/superitems npc create shop --on_right_click require has_item:emerald:5 else message &cFive emeralds please --on_right_click take emerald 5 --on_right_click give @s diamond 1

• With FancyNpcs: SuperItems runs the actions when the FancyNpcs NPC with the same name as the id is clicked. Set --link <name> (menu: FancyNpcs NPC, which lists your NPCs) to use another name. --cancel_fancy true stops FancyNpcs' own actions for that NPC. --run_as player makes every action line run as the clicking player unless the line says otherwise.
• Without FancyNpcs: /superitems npc spawn shop puts a still, invulnerable --entity (villager by default; try mannequin) where you stand. /superitems npc bind shop turns the entity you look at into the NPC, and /superitems npc unbind undoes that.
• on_click runs on every click, before on_right_click or on_left_click. --cooldown (seconds, per player) stops repeated clicks.
• /superitems npc click <id> <player> runs the actions from a command block.

12. Textures and the resource pack

Custom looks need a resource pack. SuperItems paints, builds and sends it for you.

1. Pick a model. In an item's Texture tab choose Model / texture: the default look, one of your textures, Paint a new texture, or Borrow a vanilla look (for example minecraft:dead_brain_coral). It sets --model, which also works as a command. Right click the button to paint the current texture.
2. Paint. The painter shows an 8 by 5 window of the picture; the arrows on the right move it. Left click paints, right click copies a pixel's color, shift + click fills. Tools: pen, eraser, fill, picker, mirror, undo, starter pictures (gem, orb, blade, wand, shield), 24 palette colors plus any hex color. It saves when you close it. Pictures up to 64x64 can be painted. Your own PNGs dropped into plugins/SuperItems/pack/textures appear in the Texture studio at once (the file name is the texture name, used as model superitems:<name>).
3. Build. Build the pack (studio, Resource pack menu, or /superitems pack build) writes pack/build/SuperItemsPack.zip and its SHA-1. It adds an item definition, model and texture per model in use, picks the handheld look for swords and tools, and copies everything in pack/extra as it is (use it for sounds, fonts, armor models and other pack files). The same content always gives the same SHA-1.
4. Deliver. Set resource-pack.url and sha1 (the menu fills the hash in), then turn on send-on-join and, if you like, required. No file host? Web server serves the zip from this server on resource-pack.host.port once host.public-address is set (open that port). /superitems pack send [player] tests it, /superitems pack status shows the state. The pack range written to pack.mcmeta is min-format / max-format in config.yml (84 is Minecraft 26.1, 88 is 26.2).

13. Files and config

plugins/SuperItems/: items.yml, sets.yml, mobs.yml, loot.yml, spawners.yml, recipes.yml, npcs.yml, regions.yml, variables.yml (written by the plugin every 30 seconds; change values with /superitems var), config.yml, plus history/, exports/, imports/ and pack/ (textures/, extra/, build/). Edit the yml files by hand, then /superitems reload. config.yml keys: default-material, cooldown-message, damage-indicators, damage-indicator-format, natural-replacement, history-limit and the resource-pack section.

14. Troubleshooting

• "No mob called ...": create the mob before the spawner/loot that references it.
• Nothing happens on edit: a flag was invalid; read the chat error.
• Spawner idle: no player within --range, or --max already alive.
• Menu text prompt does nothing: type your answer in normal chat; cancel goes back. A value cannot contain a word starting with two dashes, except --as_player, --as_op and --as_console.
• Texture shows as a purple and black square: the pack is not loaded yet or the model has no texture file. Build the pack, check Check everything, and resend it.
• Mob edits not showing: behavior edits apply to live mobs, but name/gear/stats only apply to newly spawned ones.
• An if line does nothing: check the line in Check everything, or try the condition with /superitems var test .... var_local needs the player to stand inside a region.
• FancyNpcs clicks do nothing: the console should log "Hooked into FancyNpcs" at startup. The SuperItems NPC id (or --link) must match the FancyNpcs NPC name.