WarpStones

About

WarpStones is a Paper plugin for Minecraft 1.21.X that introduces a fully custom warp system built around a personal Warp-Menu — a compass item each player carries that opens their own GUI. Players collect Warp Stones (custom player-head items) and place them into their menu to permanently unlock /warp destinations.

Every player progresses at their own pace: the first four slots are free, while additional slots must be purchased through an economy system. Extra pages can be unlocked for players with the appropriate permission. The plugin integrates seamlessly with EssentialsX for warp teleportation, Vault for economy-based slot purchasing, and PlaceholderAPI for scoreboard & tablist support.

---

Features

🧭 Personal Warp-Menu

• Each player receives a Warp-Menu compass that opens their own private GUI
• Right-clicking a bare Warp Stone in hand shows a preview of its destination without opening the menu
• Optionally given automatically on first join, configurable via give-menu-on-join
• Hotbar slot is configurable via menu-slot

💎 Warp Stones

• Collectible player-head items with custom textures, names, and lore
• Each stone is tied to a specific /warp destination and optional category
• Players place a stone into their Warp-Menu to permanently unlock that warp
• Fully custom display names and lore with & color codes, or clean defaults
• Optional permission node per stone to restrict who can use it (e.g. warpstones.use.vip_lounge)
• Optional per-stone cooldown in seconds between teleports

🔒 Slot System

• Page 1 starts with 4 slots unlocked for free; slots 5–8 require a purchase
• Slots must be unlocked in order — the next purchasable slot shows its price; others show a "Unlock previous first" hint
• Each page holds up to 8 warp destinations
• Sort button in the GUI rearranges placed stones alphabetically (A→Z) with a single click
• Collection progress item shows how many stones are placed and how many slots are unlocked on the current page

📄 Multi-Page Support

• Players can unlock additional pages with the warpstones.extrapage permission
• The total number of pages is defined by upgrades.yml — no hardcoded limit
• Customizable navigation arrow textures for prev/next page buttons

⏱️ Teleport Cooldowns

• Set a cooldown (in seconds) per Warp Stone via the cooldown: field
• Players receive a clear message with the remaining time if on cooldown
• Cooldown is enforced both via GUI button and direct /warp command

✨ Teleport Effects

• Configurable sound and particle effect on every teleport
• Fully adjustable: sound name, volume, pitch, particle type, and particle count
• Set either to "" to disable

🗂️ Categories

• Assign a category: to each Warp Stone (e.g. Economy, Towns, Resources)
• Category is shown in the placed-stone lore inside the GUI
• Helps players visually organize their warps at a glance

🎨 GUI Layout

• Clean 54-slot GUI (6 rows) with stone slots and action slots side by side
• Book progress indicator in the top center
• Hopper sort button in the bottom center
• Unlocked & filled slots show the Warp Stone head and a green Teleport button
• Unlocked & empty slots show a white pane and a gray Empty Slot hint
• Locked slots display a red pane with a buy button or a "locked" indicator

🔌 Developer API

• Three custom Bukkit events: WarpStoneTeleportEvent, WarpStoneUnlockEvent, WarpStonePlaceEvent — all cancellable
• Other plugins can hook into warp, unlock, and place/remove actions

🛠️ Admin Commands

• /warpstones create <id> <warp> — generate a new Warp Stone config file with full developer comments
• /warpstones give menu <player> — give a player their Warp-Menu
• /warpstones give warpstone <id> <player> — give a specific Warp Stone to a player
• /warpstones setwarp <name> — set a warp location at your current position
• /warpstones info <player> — view a player's placed stones, unlocked slots, and last warp
• /warpstones reset <player> — fully reset a player's WarpStones progress
• /warpstones reload — reload all configs and stone definitions live

---

How It Works

1. Obtain a Warp-Menu — players receive one on join (if enabled) or via /warpstones give menu
2. Collect Warp Stones — distributed by admins via command, or placed in shops/loot tables
3. Preview a stone — right-click it in hand to see the destination, category, and instructions
4. Place a stone — open the Warp-Menu and drag the stone into an unlocked slot to permanently register that warp
5. Use /warp — the plugin checks that the player has the stone placed, the required permission, and is not on cooldown
6. Sort & organize — click the Sort button to arrange placed stones alphabetically
7. Unlock more slots — click the red Unlock Slot button to purchase additional slots
8. Expand to new pages — once all 8 slots are unlocked and the player has warpstones.extrapage, a next-page arrow appears

---

Compatibility

Dependency	Type	Notes
PaperMC 1.21.X	Required	Must run on Paper or a Paper fork
EssentialsX	Optional	Used for /warp teleportation; built-in fallback via warps.yml
Vault	Optional	Required for economy-based slot unlock costs
PlaceholderAPI	Optional	Exposes placeholders for scoreboards & tablist

---

PlaceholderAPI

Placeholder	Description
%warpstones_placed%	Number of Warp Stones placed in the player's current menu
%warpstones_slots_unlocked%	Total number of unlocked slots across all pages
%warpstones_last_warp%	The last warp destination the player used

---

Configuration Highlights

• give-menu-on-join — auto-give Warp-Menu on first join
• menu-slot — hotbar slot (0–8) for the Warp-Menu
• next-page-texture / prev-page-texture — Base64 head textures for navigation arrows
• teleport-sound / teleport-particle — effects played on every teleport
• upgrades.yml — slot unlock costs per page and slot; defines the max number of pages
• warpstones/<id>.yml — one file per stone: name, warp, texture, category, permission, cooldown, optional display-name / lore

---

Permissions

Permission	Default	Description
warpstones.admin	OP	Access to all /warpstones admin commands
warpstones.extrapage	OP	Allows unlocking and viewing pages beyond page 1
warpstones.give.menu	OP	Allows using /warpstones give menu
warpstones.give.warpstone	OP	Allows using /warpstones give warpstone
warpstones.info	OP	Allows using /warpstones info
warpstones.reset	OP	Allows using /warpstones reset

---

Support & Feedback

• 📝 Leave a Review on Modrinth
• 🔄 Share with others

For questions, suggestions & bug reports: [Join the Discord to create a ticket!]