Page 3

SuperItems 2.0 (GUI): 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. 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).

10. Files and config

plugins/SuperItems/: items.yml, sets.yml, mobs.yml, loot.yml, spawners.yml, 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.

11. 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.
• 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.