⚔️ PAPERMC PLUGIN SKILL & KNOWLEDGE BASE ⚔️

Stop writing legacy Spigot code like it's 2014. Build for modern Paper & Folia with pure speed, thread-safety, and zero lag.

⚡ Quickstart • 💎 Key Features • 📚 10 Masterclass Guides • 🔍 Battle-Tested References • 🤖 AI Agent Skill

---

🚀 Instant Quickstart (5 Seconds!)

You don't need to configure Gradle or clone anything manually. Scaffold a production-grade, Folia-ready Paper plugin right now with one command:

npx papermc-skill create MyEpicPlugin

Or install the AI skill globally so your coding agents (Antigravity, Cursor, Copilot) write flawless Paper 1.21+ code:

npx papermc-skill install-skill --global

To browse architectural cheat sheets directly in your terminal:

npx papermc-skill docs

To check for the newest Minecraft & PaperMC releases from the official API:

npx papermc-skill check-update

---

💎 Why Modern Paper Matters

The Minecraft server ecosystem has evolved dramatically. Legacy habits lead to server lag spikes, thread collisions, and fatal crashes on modern engines:

Feature	💀 Legacy Spigot / Bukkit	⚡ Modern Paper & Folia (1.20.6 / 1.21+)
Color & Text	ChatColor.RED + "§lText"	Kyori Adventure & MiniMessage: <gradient:#ff007f:#7f00ff><bold>Text</bold></gradient>
Persistent Data	Third-party NBT hacks / Lore reading	PersistentDataContainer (PDC): Native, type-safe NBT on Items, Entities, Chunks, and Worlds.
Command System	plugin.yml + setExecutor(...)	Paper Native Brigadier: Client-side syntax validation, auto tab-completion directly in Mojang's engine.
Multi-Threading	Single main thread (BukkitScheduler)	Threaded Regions (Folia): Independent regional ticking via RegionScheduler & EntityScheduler.
Server Internals	Obfuscated Spigot remapping	Paperweight Userdev: Direct, unmapped access to Mojang Mappings (net.minecraft.*) at runtime.

---

📚 10 Masterclass Technical Guides

Written by developers for developers, covering everything from basic setup to high-throughput concurrency:

#	Masterclass Guide	Focus & Highlights
01	Modern Paper Architecture	paper-plugin.yml, PluginBootstrap vs JavaPlugin, Gradle paperweight-userdev, and runtime Mojang mappings.
02	Adventure API & MiniMessage	Hex gradients, dynamic TagResolver placeholders, ComponentLogger, Titles, BossBars, and Sound playback.
03	PersistentDataContainer (PDC)	Custom NBT on ItemStacks, Entities, and Chunks; implementing custom PersistentDataType<T, Z> for Java records.
04	Modern Brigadier & Cloud Commands	Native Mojang Brigadier trees via LifecycleEvents.COMMANDS, argument suggestions, and Incendo Cloud.
05	Concurrency & Folia Compatibility	Threaded regions, region schedulers, entity schedulers, async schedulers, and universal platform wrappers.
06	Event System & Paper Listeners	Paper-exclusive events (AsyncChatEvent, PrePlayerAttackEntityEvent), event priority, and custom events.
07	Best Practices & Performance Tuning	Eliminating GC memory leaks (UUID vs entity references), asynchronous chunk loading (world.getChunkAtAsync).
08	Modern GUI & Inventory Menus	Custom InventoryHolder menus, PDC interactive buttons, and bulletproof duplication-exploit prevention.
09	Custom Items, Abilities & Combat	Raycasting spells (rayTraceEntities), particle beam effects, vanilla visual cooldowns, and SFX.
10	Asynchronous Database Storage	SQLite & MySQL HikariCP connection pooling, thread-safe asynchronous DAO pattern with CompletableFuture.

---

🏛️ Cloned Reference Plugins

Nine battle-tested open-source repositories are included directly in references/ for reverse-engineering and architectural inspiration:

• 🗺️ squaremap: Production Paperweight, Incendo Cloud commands, and Folia multi-threading by PaperMC core dev jpenilla.
• ⚡ chunky: High-throughput async chunk generation engine (world.getChunkAtAsync) and multi-platform abstractions.
• 🛡️ luckperms: Enterprise permissions, HikariCP database pool, caching hierarchy, and custom event bus.
• 🏷️ miniplaceholders: Advanced Kyori Adventure API and custom MiniMessage tag resolvers.
• 💰 vault-api: The industry-standard economy and permissions bridge API.
• 🛠️ run-paper: The instant local Paper/Folia runner Gradle plugin.
• 👻 decentholograms: Protocol display entity manipulation, floating text, and packet optimizations.
• 📊 bstats: Global plugin telemetry and metrics integration.
• 🧪 paperweight-test-plugin: Official PaperMC Mojang mapping testbed.

---

🛠️ Runnable Starter Template

A battle-ready project is pre-configured in templates/paper-modern-template/:

# Navigate to the template
cd templates/paper-modern-template

# Launch an automated Paper test server in 60s
./gradlew runServer

# Or launch on multi-threaded Folia
./gradlew runFoliaServer

---

🤖 AI Agent Integration

This repository includes a machine-readable coding skill in skills/paper-plugin-dev/SKILL.md.

When pair-programming with AI coding agents:

• Tell your agent: "Use the paper-plugin-dev skill".
• The agent will automatically generate Folia-safe schedulers, MiniMessage components, Brigadier command trees, and PDC data holders with zero legacy anti-patterns.

---

📦 Packages & Distribution

Channel	Identifier / Command	Link
NPM Global	npx papermc-skill
GitHub Packages	@ardianryan/papermc-skill	GitHub Packages Hub
Release Asset	papermc-skill-v1.0.1.zip	Latest GitHub Release

---

🌟 Show Your Support!

If this toolkit helped you or your server project, give this repository a Star ⭐ on GitHub!

Minecraft is a registered trademark of Mojang Synergies AB. This project is not affiliated with or endorsed by Mojang Synergies AB, Microsoft Corporation, or PaperMC.