⚔️ 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 • 📚 11 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

To audit any plugin codebase for exploits, memory leaks, and anti-patterns:

npx papermc-skill audit

💎 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. |

📚 11 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. | | 11 | Security & Exploit Prevention | Eliminating dupe glitches, inventory race conditions, PDC tamper verification, numeric/economy validation, and packet DoS defense. |

🏛️ 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.1.0.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.