---

---

✨ What is URLDrop?

URLDrop is an admin-focused plugin that turns your Minecraft server into a download station.
Instead of SSH-ing into your machine to wget a backup or a world archive, you open a
chest GUI in-game, paste a URL, choose a destination, and let the server do the rest.

Perfect for:

• 📦 Downloading server backups from remote storage
• 🌍 Pulling world archives or data packs
• 🔌 Staging plugin updates without leaving the game
• 📁 Migrating large files between servers via URL

---

🖥️ GUI Overview

Open with /urldrop or /ud:

Screen	Description
Main Menu	Hub for all actions
New Download	5-step wizard: URL → path → filename → checksum → confirm
Active Downloads	Live progress bars, speed, ETA, cancel button
Queue	Reorder, start-now, or remove pending jobs
History	Re-download or purge completed entries
Settings	Toggle runtime options without reloading

---

⚡ Features

Downloads

• ✅ Async downloads on Java 21 virtual threads — zero main-thread blocking
• ✅ HTTP streaming directly to disk — no RAM spike for large files
• ✅ HTTP Range resume — picks up where it left off if interrupted
• ✅ Configurable retry with exponential back-off
• ✅ Automatic progress tracking (speed, ETA, % complete)
• ✅ Auto-unzip .zip archives after download
• ✅ Backup existing files before overwrite (with retention limit)

Security

• 🔒 Path traversal prevention (.. blocked before and after normalization)
• 🔒 URL validation — http/https only, optional domain whitelist/blacklist
• 🔒 Blocked file extensions / content-type filtering
• 🔒 Optional SHA-256 checksum verification before file is placed
• 🔒 Downloads stage to a temp file first, then atomically move to destination
• 🔒 File size hard cap (default 2 GB)

Destinations

• 📂 Any path the server process can reach (relative or absolute)
• 📂 Works with Pterodactyl (/home/container/...)
• 📂 Configurable path aliases (e.g. type backup → resolves to backups/)

Notifications

• 💬 Clickable in-game Adventure messages with [Retry] / [History] buttons
• 🔔 Operator join reminders for downloads that finished while you were offline
• 🟣 Discord webhook support with rich embeds

Commands

/ud                         Open GUI
/ud download <url> <path>   Start immediately
/ud queue <url> <path>      Add to queue
/ud status [id]             Show progress
/ud cancel <id>             Cancel
/ud retry <id>              Retry failed download
/ud history                 Recent history in chat
/ud debug <id>              Full diagnostics
/ud reload                  Reload config

---

⚙️ Configuration

Four config files are generated on first run:

File	Purpose
config.yml	Limits, timeouts, retry, security, notifications
messages.yml	All messages (MiniMessage format — fully customisable)
paths.yml	Aliases, sensitive paths, blocked fragments
webhook.yml	Discord webhook URL and event toggles

Quick example — config.yml

max-simultaneous-downloads: 3
max-file-size-mb: 2048
allow-resume: true
auto-unzip: false
require-checksum-for-sensitive-paths: false
operator-notify-on-complete: true

Quick example — paths.yml aliases

aliases:
  backup: "backups"
  update: "plugins/update"
  home:   "/home/container"

---

🔐 Permissions

Permission	Description
urldrop.admin	All permissions
urldrop.open	Open the GUI
urldrop.download	Start downloads
urldrop.queue	Queue downloads
urldrop.cancel	Cancel downloads
urldrop.history	View history
urldrop.settings	Toggle settings
urldrop.reload	Reload config
urldrop.debug	View diagnostics

All permissions default to operator only.

---

📋 Requirements

Requirement	Version
Server	Paper 1.21.x
Java	21+

No other plugins required. Gson is bundled inside the JAR.

---