ShardPulse

Hardcore SMP economy, raid warfare, and PvP suite built for Paper, Purpur, and Folia across Minecraft 1.21.1 – 26.3 (Java 21 & Java 25).

Works standalone out of the box with its own dual-currency ledger (Money + ✦ Shards) or hooks automatically into Vault and PlaceholderAPI. Supports YAML, SQLite, and cross-server MySQL storage with automatic data migration.

---

Why Use ShardPulse?

Hardcore economy and raiding SMPs frequently run into three gameplay problems:

1. Single-Farm Hyperinflation: Fixed /sell prices allow one giant Cactus or Bamboo farm to print unlimited money forever.
2. ESP & X-Ray Base Hunting: Legitimate raiders lack a skill-based in-game mechanic to locate underground bases, while defenders have no counter-play or trap mechanics.
3. PvP Loot Scavenging & Bounty Farming: Unarmored bystanders steal gear mid-fight, and alternate accounts farm their own bounties.

ShardPulse solves all three in one modular, Folia-safe JAR without replacing your existing /ah, /shop, /tpa, or /home plugins. Every module can be hot-toggled in-game via /shardpulse admin.

---

Core Features

1. Market Pulse & Buy-Orders

Commands: /market, /orders, /appraise

• Dynamic Supply & Demand Pricing: Mass-sold commodities gradually drop toward a configurable floor (0.60x), while scarce items climb toward a ceiling (1.65x) and recover organically over time.
• 2.0x Flash Market Rush: Periodically boosts 2 random commodities to a server-wide 2.0x sell multiplier.
• Shulker-Safe Quick-Sell Dropbox (/market sell | /quicksell): Drop loose items or filled Shulker Boxes inside and close the menu to sell contents automatically—emptied Shulker Boxes and non-sellable items return safely to your inventory.
• Escrow Buy-Order Contracts (/orders | /market orders): Lock cash in escrow to request bulk items (/orders create <material> <amount> <priceEach>). Other players fill orders directly from their inventory for instant payouts, while buyers collect delivered items anytime from their Personal Delivery Vault (/orders collect) or Shift + Right-Click to cancel and refund remaining escrow.
• Chunk Stash Appraiser (/appraise | /stashworth): Scans containers, nested Shulker Boxes, and spawners in the current 16x16 chunk to calculate net worth, with an optional Verified Stash Flex chat broadcast that never leaks coordinates.

2. Amethyst Arsenal & Boosters

Commands: /amethyst, /amethyst shop, /shardpulse tip High-tier utility tools and boosters purchased with ✦ Shards that remain unsealed, tradeable, and raidable until used:

• Zero-Bobbing Live Timer & Durability Engine: Tracks real-time HH:MM:SS expiration and durability bars smoothly on Minecraft 1.21.1–26.3 without triggering held-item equip-bobbing animations.
• 5 Amethyst Power Tools:
  • Amethyst Sell Axe: Left-click or interact with a Chest/Barrel to quick-sell market commodities inside (1.15x bonus), including items inside nested Shulker Boxes while leaving the Shulker Boxes intact.
  • Amethyst 3x3 Drill (Pickaxe): Mines a 3x3 plane aligned to the targeted block face (Sneak for 1x1 precision) while respecting claim plugins, Bedrock, Spawners, and Containers.
  • Amethyst 3x3 Excavator (Shovel): Excavates 3x3 earth/sand/gravel planes (Sneak for 1x1).
  • Amethyst Timber Chopper (Axe): Fells connected tree logs up to 64 blocks in one swing.
  • Amethyst Sponge Bucket: Reusable 5x5x5 water and lava clearing siphon with configurable cooldown.
• Unsealed Personal (1.5x) & Global (2.0x) Sell Boosters: Tradeable booster crystals sold in /amethyst shop. Global Boosters display a live server-wide BossBar and allow players to run /shardpulse tip to reward the sponsor and earn free Shards (100% Mojang EULA compliant).

3. Raid Radar & Amethyst Rifts

Commands: /radar, /rift

• Echo Seismic Resonator (Raiders): Scans nearby loaded chunks (never force-loading chunks on Paper/Folia) and reports stash heat tiers plus compass direction without revealing exact XYZ coordinates.
• Sculk Signal Jammer (Defenders): Cloaks a configurable chunk radius (3-chunk radius default) against enemy Resonator scans while fueled with Shards, alerting the online owner when a scan is blocked.
• Decoy Echo Beacon (Trap Builders): Deploys a Soul Lantern decoy (75✦) that emits a fake Critical Mega-Stash radar signature to lure raiders into traps.
• Amethyst Rift Supply Drops (/rift): Scheduled world PvP event spawning a locked Respawn Anchor cache with a sky beam and BossBar lock countdown, rewarding Shards, an Unsealed Amethyst Tool, and a Personal Sell Booster.

4. Bounties, Loot-Guard & Leaderboards

Commands: /bounty, /shardpulse top

• 15s Killer Loot-Guard: Protects PvP kill drops (including melee, projectile, and End Crystal kills) from third-party scavengers and hopper theft for 15 seconds without breaking item stacking.
• Anti-Abuse Blood Bounties (/bounty): Enforces listing tax (8%), same-IP alt-account blocking, and pair claim cooldowns (30m), dropping stamped Player Trophy Skulls on PvP kills.
• Top 10 Player Skull Leaderboards (/shardpulse top): Interactive 4-tab GUI (Top Shards, Market Tycoons, Bounty Hunters, Biggest Stashes) plus hologram PlaceholderAPI tags.

---

Commands & Permissions

Command	Aliases	Permission	Description
/shardpulse [top|tip|admin|...]	/spulse	shardpulse.use / shardpulse.admin	Overview, Top 10 Leaderboards (top), Booster Tip (tip), & Admin Control GUI
/amethyst [shop|status|...]	/shards, /shardshop	shardpulse.use	View Amethyst subcommands, open the Shard Shop (/amethyst shop), & inspect tools
/market [sell|orders]	/pulse, /priceindex, /quicksell	shardpulse.use	Open Live Market Ticker, Quick-Sell Box (sell), or Buy-Orders (orders)
/orders [create|collect]	/buyorders	shardpulse.use	Escrow Buy-Order Contract Board & Personal Delivery Vault
/appraise	/stashworth, /chunkworth	shardpulse.use	Appraise container, nested Shulker, and spawner net worth in current chunk
/radar	/jammer, /seismic	shardpulse.use	Open Echo Resonator, Decoy Echo Beacon, & Sculk Signal Jammer menu
/bounty [add <player> <amount>]	/bounties, /headhunt	shardpulse.use	Open Blood Bounty Board or place a bounty
/rift [status|here|random|stop]	/supplydrop, /amethystrift	shardpulse.use / shardpulse.admin	Check active Amethyst Rift coordinates/timer or spawn/stop a Rift

Admin Subcommands (shardpulse.admin)

• /shardpulse admin — Open the in-game Admin Control Panel GUI (live module toggles, 1-click test kit, Flash Rush trigger, Rift spawn, webhook test, config reload)
• /shardpulse give <player> <SELL_AXE|DRILL|EXCAVATOR|TREE_CHOPPER|SPONGE_BUCKET|RESONATOR|JAMMER|DECOY_BEACON|PERSONAL_BOOSTER|GLOBAL_BOOSTER>
• /shardpulse shards <give|take|set> <player> <amount> — Modify player Shards balance
• /shardpulse eco <give|take|set> <player> <amount> — Modify player Money balance
• /shardpulse rush — Manually trigger a 2.0x Flash Market Rush
• /shardpulse rift <here|random|stop> — Spawn or clear an Amethyst Rift supply drop
• /shardpulse webhooktest — Send a test embed to your configured Discord webhook
• /shardpulse reload — Reload config.yml and messages.yml and flush persistent data

---

PlaceholderAPI Identifiers

Click to expand all PlaceholderAPI placeholders

• %shardpulse_shards% / %shardpulse_shards_formatted% / %shardpulse_shards_compact%
• %shardpulse_money% / %shardpulse_money_formatted%
• %shardpulse_economy_mode% / %shardpulse_storage_mode%
• %shardpulse_active_booster% — Player's combined active sell multiplier (1.00x – 3.50x)
• %shardpulse_bounty% / %shardpulse_bounty_formatted% / %shardpulse_has_bounty%
• %shardpulse_rush_active% / %shardpulse_rush_items%
• %shardpulse_price_<MATERIAL>% / %shardpulse_trend_<MATERIAL>%
• %shardpulse_top_<shards|market|bounty|stash>_<1-10>_<name|value>% — Top 10 hologram leaderboards

---

Requirements & Network Disclosure

• Server Software: Paper, Purpur (or Paper forks), and Folia (1.21.1 through 26.3). Note: Vanilla CraftBukkit and Spigot are not supported because ShardPulse uses Paper's Adventure MiniMessage and RegionScheduler APIs.
• Optional Dependencies: Vault (plus any economy provider such as EssentialsX) and PlaceholderAPI.
• Storage Backends: YAML (default, zero setup), SQLITE (local SQL file), or MYSQL (cross-server Velocity sync) in config.yml -> storage.type. Switching from YAML to SQLITE or MYSQL automatically migrates existing player balances and stats.
• Audit Logging: High-value market sales, Buy-Order escrows, bounties, Rift claims, and admin grants are logged asynchronously to plugins/ShardPulse/logs/economy-audit.log.
• External Network Connections Disclosure: ShardPulse collects zero telemetry or analytics. It makes external HTTP requests only in two administrator-controlled features:
  1. Discord Webhook Alerts (discord-webhook.enabled: false by default): Sends game event embeds solely to the Discord Webhook URL explicitly configured by the server administrator in config.yml.
  2. Hangar Update Checker (update-checker.enabled: true, hangar-project: "" blank by default): Performs a read-only version check against the public Hangar API (hangar.papermc.io) only if a project slug is configured, and can be disabled anytime by setting update-checker.enabled: false.