wParkour

---

🌟 Overview

wParkour is a lightweight, feature-packed procedural parkour plugin built from the ground up for high-performance Paper and Purpur 1.21+ servers.

Unlike traditional static parkour plugins where every jump is pre-built, wParkour generates infinite, intelligent jump sequences dynamically in real-time inside your custom-defined arena regions. Players never jump on the same route twice!

---

✨ Features

• 🔄 Dynamic Procedural Generation: Infinite, non-repetitive jumps generated dynamically ahead of the player. The generator intelligently avoids walls, corners, and other active players.
• 🎯 Adjustable Difficulties: Support for EASY, NORMAL, and HARD modes with physics-accurate gap and height calculations.
• 📦 Exploit-Proof Reward Storage (/parkour storage):
  • If a player's inventory is full when they fall, earned items and item-giving commands are automatically routed into their personal Storage GUI.
  • Packet-Proof & Anti-UiUtils: Hardened with strict server-side cursor sanitization, synchronous row deletion verification, and click-type filtering to prevent window desyncs and dupe exploits.
  • Configurable Expiration: Storage items automatically expire after a set time (default: 24h) with real-time countdown lore in the GUI.
• 🎁 Unified Milestone Loot Pool:
  • Add item rewards via an intuitive drag-and-drop GUI or command rewards (e.g. /eco give %player% 100).
  • Configurable win chances (%) and milestone intervals (e.g. every 10 or 50 jumps).
  • Consolidated rolling ensures strictly one reward per milestone—no unfair double rewards!
• 🎨 Personal Cosmetic Blocks:
  • Players receive an interactive block selector chest item while parkouring to customize the look of their own generated blocks.
• 🏆 Interactive Toplist Holograms:
  • Automatically spawned floating TextDisplay holograms above activator pressure plates showcasing the arena's top parkour runners.
  • Chunk-safe and auto-recovering across server restarts and unloads.
• 💾 Robust SQLite Engine:
  • Uses high-performance SQLite in WAL (Write-Ahead Logging) mode with busy timeout handling.
  • Includes crash and restart inventory recovery (saved_inventories).
• ⚡ Zero-Flicker Hitbox Detection:
  • Uses accurate Axis-Aligned Bounding Box (AABB) edge detection—players don't need to land dead-center on blocks for jumps to register.

---

🎮 Player Commands

Command	Permission	Description
/parkour storage	None	Opens your personal unclaimed rewards storage GUI.
/wparkour start <arena>	wparkour.play	Starts parkour in the specified arena.
/wparkour list	wparkour.play	Lists all available parkour arenas.
/wparkour leave	wparkour.play	Leaves your current parkour run and restores your inventory.

---

🛠️ Admin Commands

Command	Permission	Description
/wparkour pos1	wparkour.admin	Sets the first corner point for a new arena.
/wparkour pos2	wparkour.admin	Sets the second corner point for a new arena.
/wparkour create <name>	wparkour.admin	Creates a new arena within the selected region.
/wparkour item <name>	wparkour.admin	Gives you an activator pressure plate for the arena.
/wparkour setspawn <name>	wparkour.admin	Sets the respawn/teleport location for the arena.
/wparkour difficulty <name> <easy|normal|hard>	wparkour.admin	Changes the jump generation difficulty.
/wparkour config <name> reward-interval <number>	wparkour.admin	Sets the default reward frequency (e.g. every 10 jumps).
/wparkour rewards [name]	wparkour.admin	Opens the GUI to configure items, chances, and commands.
/wparkour start <name> [player]	wparkour.admin	Forces a parkour start for yourself or another player.
/wparkour resetstats <player | *>	wparkour.admin	Clears high scores for a specific player or everyone (*).
/wparkour delete <name>	wparkour.admin	Deletes an arena and cleans up its data.
/wparkour reload	wparkour.admin	Reloads config.yml, messages.yml, and rewards without restarting.

---

🔐 Permissions

Permission	Default	Description
wparkour.play	true	Allows players to use parkour arenas and start runs.
wparkour.admin	op	Grants access to all admin setup and management commands.
wparkour.toplist.bypass	false	Players with this permission will not appear on toplist holograms.

---

🚀 Quick Setup Guide

1. Select Arena Boundaries:
   • Stand at corner 1 and type /wparkour pos1.
   • Stand at corner 2 and type /wparkour pos2.
2. Create Arena:
   • Type /wparkour create MyArena.
3. Set Return Spawn:
   • Stand where players should spawn when falling or leaving and type /wparkour setspawn MyArena.
4. Place Start Pressure Plate:
   • Type /wparkour item MyArena to get the activator pressure plate.
   • Place it on any solid block (a toplist hologram will automatically appear above it!).
5. Configure Rewards:
   • Type /wparkour rewards MyArena.
   • Click items from your own inventory into the GUI to add item rewards.
   • Use the command block button to add command rewards (e.g. eco give %player% 50).
   • Use Shift + Right Click on any item or command to toggle whether it should route to /parkour storage if a player's inventory is full.

---

⚙️ Configuration (config.yml)

# Gameplay settings
gameplay:
  fall-y-threshold: 2.2      # Blocks below lowest active block before trigger fall
  chest-slot: 4              # Inventory slot for the cosmetic block selector chest

# Reward Storage (/parkour storage)
storage:
  # How long unclaimed rewards are stored in hours (default: 24h, 0 = never expires)
  expiration-hours: 24

# Toplist settings
toplista:
  # Permission to exclude staff/admins from holograms
  bypass-permission: "wparkour.toplist.bypass"
  # Refresh interval in seconds for top scores
  frissitesi-ido: 300

---

🧩 Placeholders

In command rewards, you can use the following dynamic placeholders:

• %player% or <player> - The player's name
• %player_uuid% - The player's UUID
• %score% - The jump score reached when the reward was triggered

---

📋 Compatibility & Requirements

• Server Software: Paper, Purpur, or Folia compatible fork (1.21.x+)
• Java: Java 21 or newer
• Dependencies: None! (SQLite database is embedded and auto-configured)
• Soft Dependencies: PlaceholderAPI (optional)

---

💬 Support & Community

Need help configuring wParkour, have questions, or want to suggest new features? Join our official community Discord!

• 🌐 Discord Server: dc.coolnw.eu
• 🌐 Website: coolnw.eu

---