⚔ Scword — Custom Items Management

Scword is a high-performance Paper 1.21.4 plugin for creating, managing, and tracking custom items with advanced features like crafting recipes, item limits, exclusive lifetime tracking, a modular ability system, Discord webhook notifications, and a full-featured GUI editor.

Features Weapon Creation & Editing

• Create weapons from scratch or capture items directly from your hand
• Full MiniMessage support for names, lore, and text formatting
• Custom model data and ItemsAdder integration
• Enchantments, attributes, and per-item NBT-tracked statistics

Ability System

• Modular system with 9+ abilities and configurable triggers
• Abilities: Fire (ignite), Freeze (slow), Poison, Vampire (heal on kill), AOE (area damage), Throw (boomerang), Solar Flare, Fortitude (defense), Leveling
• Trigger types: ON_HIT, RIGHT_CLICK, LEFT_CLICK, ON_KILL, ON_BLOCK_BREAK, ON_SNEAK, ON_TAKE_DAMAGE
• Per-ability cooldowns, activation chances, and configurable parameters

Recipe System

• Visual 3×3 recipe editor GUI (SHAPED and SHAPELESS support)
• Quick-Craft GUI — pre-fills materials from the player's inventory
• Auto-detect when a player has enough materials (craft notifications)
• Shift-click bulk crafting with limit/exclusivity enforcement

Item Limits

• GLOBAL (server-wide) or LOCAL (per-player) concurrent item caps
• Reset modes: NEVER, FULL_RESET (cooldown-based cycles), PER_CRAFT (cooldown between crafts)
• Configurable cooldown durations
• Permission bypass: scword.bypass.limit

Exclusive Limited Items Lifetime tracking system — controls how many times an item can ever be obtained:

Type	Behavior	Best For
TOTAL_SERVER	Only X copies can ever exist server-wide	Event items, one-time rewards
PER_PLAYER	Each player can only obtain Y copies ever	Starter weapons, rank rewards
TIMED	Only obtainable within a date/time window	Seasonal items, holiday events
COMBINATION	All three enforced simultaneously	Ultra-rare limited items

Key behaviors:

• Exclusivity takes priority over normal limits — when both are enabled, only exclusivity is checked
• Counts persist in exclusive_data.yml (debounced auto-save, crash-safe)
• prevent_give flag controls whether /scword give bypasses exclusivity
• Exclusive lore line (✦ Limited Edition: 3/10 remaining) auto-appends to items
• Admin reset command: /scword exclusivereset <id> --confirm

Craft Notifications

• Automatically notifies players when they have materials for a craftable weapon
• Clickable chat message opens the Quick-Craft GUI
• Configurable cooldown (default: 30s) and sound effect

Discord Webhooks

• Real-time notifications for crafting, destroying, and availability of limited items
• Fully customizable embed templates, colors, thumbnails, and mentions
• Per-weapon thumbnail and notification overrides

️ Full GUI Editor

• Weapon list with pagination, search, and quick actions
• Inline chat input for names, lore, and numeric configuration
• Sections: Properties, Name/Lore, Limits, Exclusive, Recipe, Abilities, Save/Give

Auto-Migration

• Config migration: Missing config keys are auto-added from defaults on reload (never overwrites user values)
• Weapon migration: Old weapon YAML files automatically get the exclusive section with defaults

Commands

Command	Permission	Description
/scword gui	scword.gui	Open the weapon management GUI
/scword list	scword.use	List all weapons with current counts
/scword give <id> [player] [amount]	scword.give	Give a weapon to yourself or another player
/scword craft <id>	scword.use	Open the quick-craft GUI for a weapon
/scword create <id> <material|[hand]>	scword.admin	Create a new weapon
/scword limit <id> <max>	scword.admin	Set the concurrent item limit
/scword webhook <test|status|reload>	scword.admin	Manage Discord webhook
/scword reload	scword.reload	Reload plugin configs and weapons
/scword exclusivereset <id> [--confirm]	scword.admin	Reset exclusive lifetime counts
/scword help	—	Show the help menu

Permissions

Permission	Default	Description
scword.use	OP	Basic plugin usage (list, craft)
scword.admin	OP	Full admin access (create, limit, webhook, exclusivereset)
scword.give	OP	Give weapons to players
scword.reload	OP	Reload the plugin
scword.gui	OP	Access the GUI editor
scword.bypass.limit	OP	Bypass item limits and exclusivity

⚙️ Configuration config.yml
Weapon YAML Structure (weapons/example_weapon.yml)
GUI Editor Access with /scword gui. The weapon list shows all weapons with pagination, current limit counts, and quick actions. Click a weapon to enter the editor:

Slot	Setting	Controls
Properties	Unbreakable, hide flags/stats/enchants/glint	Click to toggle
Name	Display name (MiniMessage)	Click to type in chat
Lore	Lore lines (MiniMessage, {stat:key} placeholders)	Click to edit
Limits	Toggle on/off, max, type (GLOBAL/LOCAL), reset mode, cooldown	Click/cycle
Exclusive	Toggle, type (shift+click), lifetime max (click), player max (right-click), time window (shift+right-click)	Multi-interaction
Recipe	Open the 3×3 visual recipe editor	Click to open
Abilities	Manage all abilities with parameters	Click to configure
Save	Save to disk	Click
Give	Give yourself the weapon	Click

Exclusive GUI Controls

• Left-click Exclusive Config button → cycle lifetime max presets (1→5→10→25→50→100→unlimited)
• Shift+left-click → cycle exclusive type (TOTAL_SERVER→PER_PLAYER→TIMED→COMBINATION)
• Right-click → set per-player max via chat input
• Shift+right-click → set time window (start,end) via chat input

Exclusive Limited Items — Deep Dive Priority Behavior When both normal limits and exclusive limits are enabled on a weapon, exclusivity takes priority. The normal concurrent limit is ignored in favor of the lifetime exclusive tracking. Example:

• limit_max: 12 (normal — max 12 concurrent)
• lifetime_max: 14 (exclusive — only 14 ever)
• Result: All 14 can be crafted, regardless of the normal limit of 12

Data Persistence

• Counts are stored in plugins/Scword/exclusive_data.yml
• Auto-saved via debounced write (2 ticks after last craft)
• Also saved on plugin disable and reload
• Admin reset: /scword exclusivereset <id> --confirm

Exclusive Lore Weapons with a TOTAL_SERVER lifetime limit automatically show a dynamic lore line based on how many copies remain:

Scenario	Default Lore	Config Key
Only 1 can ever exist	✦ The One and Only — 1/1	exclusive-lore-singular
First one crafted	✦ First Edition — 1/10	exclusive-lore-first
Last remaining copy	✦ The Last — 10/10	exclusive-lore-last
All copies exhausted	✦ No More Remain — 10/10	exclusive-lore-none-left
Normal (mid-range)	✦ Limited Edition: #3/10 remaining	exclusive-lore

All keys are configurable via messages in config.yml. Available placeholders:

Placeholder	Description
{max}	Total lifetime_max configured
{remaining}	How many more can be obtained
{obtained}	How many have been obtained (0-indexed)
{obtained_plus_one}	This item's sequence number (1-indexed)

To customize, add any of the keys to your config.yml messages section. They will be auto-merged on next reload.
Craft Notifications When a player picks up items, clicks in an inventory, or closes a chest, the plugin checks if they have materials for any enabled recipe: Configuration

• Cooldown: craft-notification-cooldown (seconds, default 30)
• Sound: craft-notification-sound ("SOUND,volume,pitch" or "none" to disable)
• Tracks per-player state — won't re-notify until materials are lost and regained

Data Files

File	Purpose
plugins/Scword/config.yml	Main plugin configuration
plugins/Scword/weapons/*.yml	Individual weapon definitions
plugins/Scword/webhook.yml	Discord webhook configuration
plugins/Scword/exclusive_data.yml	Exclusive lifetime counts (auto-managed)

Auto-Migration

• config.yml: Missing keys are auto-merged from defaults on every load — never overwrites user values
• weapon YAML files: Old weapons without the exclusive section get it added automatically with defaults on load

PlaceholderAPI Expansion When PlaceholderAPI is installed, Scword registers the scword expansion automatically. All placeholders follow the format: Where <weaponId> is the weapon's ID (e.g. hellfire_blade). Since types are single words, weapon IDs with underscores work naturally. Exclusive Placeholders

Placeholder	Returns	Example
%scword_exclusive_obtained_<id>%	Server-wide lifetime crafts	%scword_exclusive_obtained_hellfire_blade% → 3
%scword_exclusive_remaining_<id>%	Remaining lifetime capacity	%scword_exclusive_remaining_hellfire_blade% → 7
%scword_exclusive_max_<id>%	Configured lifetime_max	%scword_exclusive_max_hellfire_blade% → 10
%scword_exclusive_canobtain_<id>%	Whether anyone can still obtain it	%scword_exclusive_canobtain_hellfire_blade% → true
%scword_exclusive_lore_<id>%	The dynamic exclusive lore line (MiniMessage)	%scword_exclusive_lore_hellfire_blade% → ✦ First Edition — 1/10

Per-Player Placeholders These require a player context (e.g. in a player's chat message, sign, or hologram that has access to the viewing player).

Placeholder	Returns	Example
%scword_exclusive_playerobtains_<id>%	How many times the player has obtained it	%scword_exclusive_playerobtains_hellfire_blade% → 1
%scword_exclusive_playermax_<id>%	Configured player_max	%scword_exclusive_playermax_hellfire_blade% → 3
%scword_exclusive_playerremaining_<id>%	Remaining per-player capacity	%scword_exclusive_playerremaining_hellfire_blade% → 2
%scword_exclusive_canobtainplayer_<id>%	Whether the player can obtain it	%scword_exclusive_canobtainplayer_hellfire_blade% → true

Usage Examples In item lore (via PlaceholderAPI in chat/minimessage): In holograms / scoreboards: Conditional display (e.g. in PlaceholderAPI conditionals):
Note from developer: The plugin is built for my minecraft server and is experimental! If you encounter any bugs kindly report it to me thank you! (ONLY TESTED ON A 1.21.11 SERVER)