papermc-skill 1.1.0 → 1.2.0

package/.cursor/rules/paper-plugin-dev.mdc

@@ -0,0 +1,23 @@
+---
+description: Modern Paper & Folia Minecraft Java plugin development standards
+globs: **/*.java, **/*.gradle.kts, **/paper-plugin.yml, **/config.yml
+---
+
+# Modern Paper & Folia Plugin Development Rules
+
+When editing or generating code in this Minecraft plugin project:
+
+- **Target API**: PaperMC 1.21+ / 26.x on Java 21+ with `folia-supported: true`.
+- **Text & Colors**: Exclusively use Kyori Adventure `Component` and `MiniMessage.miniMessage().deserialize(...)`. Ban `org.bukkit.ChatColor` and `§`.
+- **Items**: Use `DataComponentTypes` (e.g. `FOOD`, `TOOL`, `CUSTOM_MODEL_DATA`). Never touch legacy NBT or reflection.
+- **Holograms**: Spawn `TextDisplay` or `ItemDisplay` with `Billboard.CENTER` and interpolated JOML `Matrix4f` transformations. Never use `ArmorStand`.
+- **Folia Multi-Threading**:
+  - Never call `Bukkit.getScheduler()` for tick tasks without checking Folia compatibility.
+  - Entity mutations: `entity.getScheduler()`.
+  - World/block mutations: `Bukkit.getRegionScheduler()`.
+  - Database & I/O: 100% async (`Bukkit.getAsyncScheduler()`).
+- **Security & Dupes**:
+  - Cancel GUI clicks and apply 200ms debounce.
+  - Store `UUID` instead of `Player` references in static maps to avoid memory leaks.
+  - Reject `NaN`, `Infinity`, and negative values in commands.
+- **Verification**: Run `npx papermc-skill audit` before finishing work.

package/.cursorrules

@@ -0,0 +1,6 @@
+# Cursor Rules: Modern Paper & Folia Development
+- Use Kyori Adventure & MiniMessage (`<green>`, `<gradient:...>`). Never use ChatColor or '§'.
+- Use DataComponentTypes for items.
+- Use Display Entities with JOML Matrix4f transformations for holograms.
+- Adhere to Folia region-threading rules.
+- Audit security using `npx papermc-skill audit`.

package/.paseo/rules.md

@@ -0,0 +1,8 @@
+# Paseo Agent Rules: Paper & Folia Development
+
+- Target: PaperMC 1.21+ / 26.x with Folia region threading support.
+- Text: Kyori Adventure + MiniMessage only. Legacy ChatColor and '§' are banned.
+- Items: Use DataComponentTypes (MC 1.20.5+ through 26.x). Zero raw NBT.
+- Holograms: Use TextDisplay / ItemDisplay with interpolated JOML transformations.
+- Concurrency: Thread-safe region scheduling. All I/O and DB queries must run asynchronously.
+- Security: Enforce click debounce on GUIs, sanitize numeric inputs against NaN, run `npx papermc-skill audit`.

package/.pi/rules.md

@@ -0,0 +1,8 @@
+# pi.dev Agent Directives: Modern Minecraft Plugin Architecture
+
+- Enforce Kyori Adventure and MiniMessage.
+- Never use legacy ChatColor or § color codes.
+- Use DataComponentTypes for items (1.20.5+ / 26.x).
+- Avoid ArmorStands for holograms; use Display Entities (TextDisplay, ItemDisplay) with smooth client-side interpolation.
+- Preserve Folia region-threading safety with RegionScheduler and EntityScheduler.
+- Audit security using `npx papermc-skill audit`.

package/.windsurfrules

@@ -0,0 +1,7 @@
+# Windsurf Rules: Modern Paper & Folia Development
+
+- Exclusively use Kyori Adventure & MiniMessage (`<color>`, `<gradient>`). Legacy ChatColor is banned.
+- Items: Use DataComponentTypes (Minecraft 1.20.5+ / 26.x). No raw NBT.
+- Holograms: Use Display Entities (TextDisplay, ItemDisplay) with JOML Matrix4f transformations.
+- Concurrency: Folia region-safe scheduling (`player.getScheduler()`, `Bukkit.getRegionScheduler()`).
+- Security: Sanitize all inputs against NaN and negative bounds. Audit code using `npx papermc-skill audit`.

package/CHANGELOG.md

@@ -5,6 +5,37 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0] - 2026-11-11
+
+### Added
+- **Universal Multi-Agent Installation System (`npx papermc-skill install-skill [options]`)**:
+  - Direct installation and rule support for 8 premier AI coding agent platforms:
+    - **Google Antigravity / agy** (`~/.gemini/config/skills/paper-plugin-dev` and `.agents/skills/`)
+    - **Claude Code** (`~/.claude/skills/` and workspace `CLAUDE.md`)
+    - **OpenAI Codex** (`~/.codex/skills/` and workspace `CODEX.md`)
+    - **Cursor** (`.cursor/rules/paper-plugin-dev.mdc` and `.cursorrules`)
+    - **DeepSeek Harness** (`~/.deepseek/skills/` and workspace `DEEPSEEK.md`)
+    - **Paseo** (`~/.paseo/skills/` and workspace `.paseo/rules.md`)
+    - **pi.dev** (`~/.pi/skills/` and workspace `.pi/rules.md`)
+    - **Windsurf** (workspace `.windsurfrules`)
+  - Supports `--all`, `--agent <name>`, `--global`, `--local`, and interactive target selection prompt.
+- **Overpowered (OP) Code Generators (`npx papermc-skill generate <recipe> [name]`)**:
+  - `component-item`: Scaffolds modern Data-Component item builder (MC 1.20.5 - 26.x).
+  - `display-entity`: Scaffolds zero-lag interpolated TextDisplay & ItemDisplay hologram engine.
+  - `mace-combat`: Scaffolds 1.21 Tricky Trials Mace smash physics and shockwave knockback.
+  - `menu-gui`: Scaffolds exploit-proof inventory menu controller with 200ms click debounce.
+- **Masterclass Guide 12: Modern Data Components & Display Entities (`docs/12-data-components-and-display-entities.md`)**:
+  - Comprehensive guide on the paradigm shift from legacy NBT to DataComponentTypes (`io.papermc.paper.datacomponent`), Custom Model Data, Food properties, Tool rules, and JOML Matrix4f smooth client-side interpolation.
+- **Masterclass Guide 13: Multi-Agent System & Universal AI Tooling (`docs/13-multi-agent-system-and-tooling.md`)**:
+  - In-depth architectural setup guide for orchestrating Paper & Folia plugin development across all major AI agent harnesses.
+- **Enhanced Security Audit Scanner**:
+  - Added detection for legacy NBT manipulation (`net.minecraft.nbt`), `BukkitRunnable` on Folia, and `ArmorStand` laggy floating text anti-patterns.
+
+### Changed
+- **PaperMC & Folia Modern Versioning Support**:
+  - Updated compatibility matrix to support Paper 1.21+ through 26.x (Java 21 LTS and Java 25+).
+  - Enriched `skills/paper-plugin-dev/SKILL.md` with modern Tricky Trials combat kinematics and Data Components recipes.
+
 ## [1.1.0] - 2026-10-01
 
 ### Added

package/CLAUDE.md

@@ -0,0 +1,27 @@
+# Claude Code Instructions: Paper & Folia Minecraft Plugin Development
+
+You are an expert Minecraft server software architect specializing in modern **PaperMC**, **Folia**, **Kyori Adventure**, and **Data Components**.
+When writing or refactoring Minecraft plugin code in this project, adhere strictly to these rules:
+
+## ⚔️ Core Architectural Rules
+1. **Never use legacy `ChatColor` or section sign (`§`)**:
+   - Always use Adventure Component API and `MiniMessage.miniMessage().deserialize("<gradient:#ff0080:#7928ca>Text</gradient>")`.
+2. **Never use raw NBT (`net.minecraft.nbt`)**:
+   - In Minecraft 1.20.5+ / 1.21+ / 26.x, use `DataComponentTypes` (e.g. `itemStack.setData(DataComponentTypes.CUSTOM_MODEL_DATA, ...)`).
+3. **No Memory Leaks**:
+   - Never store `Player`, `World`, or `Entity` in static collections. Store `UUID` instead.
+4. **Folia Multi-Threading Safety**:
+   - For player/entity operations: use `player.getScheduler()`.
+   - For block/chunk operations: use `Bukkit.getRegionScheduler()`.
+   - For async tasks: use `Bukkit.getAsyncScheduler()`.
+   - Never call `Bukkit.getScheduler()` when targeting Folia.
+5. **Zero-Lag Visuals**:
+   - Never spawn invisible `ArmorStand` entities for text holograms.
+   - Use `TextDisplay` and `ItemDisplay` with JOML `Matrix4f` transformations and client-side interpolation.
+6. **Exploit & Dupe Prevention**:
+   - Debounce all custom GUI clicks (200ms cooldown).
+   - Cancel `InventoryDragEvent` and `InventoryClickEvent` by default.
+   - Sanitize all numeric input with `Double.isFinite(val)` and strict lower/upper bounds.
+   - Identify custom items through `PersistentDataContainer` (PDC), never item names or lore.
+7. **Quality Gate**:
+   - Run `npx papermc-skill audit` to verify compliance before concluding tasks.

package/CODEX.md

@@ -0,0 +1,12 @@
+# OpenAI Codex Instructions: Paper & Folia Minecraft Plugin Engineering
+
+This repository uses modern PaperMC (1.21+ / 26.x) and Folia multi-threaded architecture.
+
+## Guidelines for Codex:
+- **Build Tool**: Gradle Kotlin DSL (`build.gradle.kts`) with Java 21 LTS or Java 25.
+- **Commands**: Modern Brigadier via Paper's `LifecycleEvents.COMMANDS`.
+- **Text & UI**: Kyori Adventure with MiniMessage formatting. Legacy `ChatColor` is strictly forbidden.
+- **Item System**: Use modern `io.papermc.paper.datacomponent.DataComponentTypes` rather than NBT or reflection.
+- **Concurrency**: Respect Folia region thread boundaries. Never mutate blocks or entities off their respective region thread.
+- **Display Entities**: Use `TextDisplay` and `ItemDisplay` with JOML `Matrix4f` transformations for holograms.
+- **Security**: Prevent item dupes and memory leaks. Audit with `npx papermc-skill audit`.

package/DEEPSEEK.md

@@ -0,0 +1,18 @@
+# DeepSeek Harness Directives: Modern Paper & Folia Plugin Development
+
+Follow these production-grade principles when synthesizing or auditing Minecraft Java code:
+
+1. **Kyori Adventure & MiniMessage**:
+   - Parse rich color tags using `<green>`, `<gradient:...>`, and `<hover:show_text:...>`.
+   - Never output legacy raw format codes `§` or `ChatColor`.
+2. **Modern Data Components (MC 1.20.5 — 26.x)**:
+   - Use `DataComponentTypes` for all item customization (`FOOD`, `TOOL`, `CUSTOM_MODEL_DATA`, `MAX_STACK_SIZE`).
+3. **Thread Safety on Folia**:
+   - Entities run on isolated thread pools. Always schedule entity mutations on `entity.getScheduler()`.
+   - Never invoke blocking operations (SQL, HTTP, disk) on Bukkit or Folia region threads.
+4. **Display Entity Holograms**:
+   - Spawn `TextDisplay` or `ItemDisplay` with `Billboard.CENTER` and interpolated transformations.
+5. **Exploit Prevention**:
+   - Validate numerical arguments with `Double.isFinite()` and bounds.
+   - Guard GUIs with a 200ms debounce map.
+   - Run `npx papermc-skill audit` on code changes.

package/README.md

@@ -6,16 +6,17 @@
 
 # ⚔️ 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.**
+**Stop writing legacy Spigot code like it's 2014. Build for modern Paper & Folia (1.21+ through 26.x) with pure speed, thread-safety, zero lag, and multi-agent AI intelligence.**
 
-[![PaperMC](https://img.shields.io/badge/PaperMC-1.20.6%20%7C%201.21+-0098FF?style=for-the-badge&logo=minecraft&logoColor=white)](https://papermc.io)
+[![PaperMC](https://img.shields.io/badge/PaperMC-1.21+%20%7C%2026.x-0098FF?style=for-the-badge&logo=minecraft&logoColor=white)](https://papermc.io)
 [![Folia](https://img.shields.io/badge/Folia-Multi--Threaded%20Ready-5865F2?style=for-the-badge&logo=dependabot&logoColor=white)](https://github.com/PaperMC/Folia)
-[![Java](https://img.shields.io/badge/Java-21%2B%20LTS-ED8B00?style=for-the-badge&logo=openjdk&logoColor=white)](https://adoptium.net)
+[![Java](https://img.shields.io/badge/Java-21%2B%20LTS%20%7C%2025-ED8B00?style=for-the-badge&logo=openjdk&logoColor=white)](https://adoptium.net)
+[![Multi-Agent](https://img.shields.io/badge/AI%20Agents-Antigravity%20%7C%20Claude%20%7C%20Codex%20%7C%20Cursor%20%7C%20DeepSeek-8A2BE2?style=for-the-badge)](docs/13-multi-agent-system-and-tooling.md)
 [![NPM](https://img.shields.io/npm/v/papermc-skill?style=for-the-badge&color=CB3837&logo=npm&logoColor=white)](https://www.npmjs.com/package/papermc-skill)
 [![GitHub Release](https://img.shields.io/github/v/release/ardianryan/papermc-skill?style=for-the-badge&color=2ea44f&logo=github&logoColor=white)](https://github.com/ardianryan/papermc-skill/releases/latest)
 [![License: MIT](https://img.shields.io/badge/License-MIT-44CC11?style=for-the-badge)](LICENSE)
 
-[⚡ Quickstart](#-instant-quickstart-5-seconds) • [💎 Key Features](#-why-modern-paper-matters) • [📚 11 Masterclass Guides](#-11-masterclass-technical-guides) • [🔍 Battle-Tested References](#-cloned-reference-plugins) • [🤖 AI Agent Skill](#-ai-agent-integration)
+[⚡ Quickstart](#-instant-quickstart-5-seconds) • [🤖 Multi-Agent Setup](#-universal-ai-agent-installation) • [💎 Key Features](#-why-modern-paper-matters) • [📚 13 Masterclass Guides](#-13-masterclass-technical-guides) • [⚡ Code Generators](#-overpowered-op-code-generators)
 
 ---
 
@@ -23,50 +24,97 @@
 
 ## 🚀 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**:
+Scaffold a production-grade, Folia-ready Paper plugin right now with **one command**:
 
 ```bash
 npx papermc-skill create MyEpicPlugin
 ```
 
-Or install the AI skill globally so your coding agents (**Antigravity**, **Cursor**, **Copilot**) write flawless Paper 1.21+ code:
+Install the AI skill across all your coding agents (**Antigravity**, **Claude Code**, **Codex**, **Cursor**, **DeepSeek**, **Paseo**, **pi.dev**, **Windsurf**):
 
 ```bash
-npx papermc-skill install-skill --global
+npx papermc-skill install-skill --all
 ```
 
-To browse architectural cheat sheets directly in your terminal:
+Generate modern **DataComponent** items or **Display Entity** holograms instantly:
 ```bash
-npx papermc-skill docs
+npx papermc-skill generate component-item EpicRelicBuilder
+npx papermc-skill generate display-entity HologramController
 ```
 
-To check for the newest Minecraft & PaperMC releases from the official API:
+Audit any plugin codebase for exploits, dupe glitches, memory leaks, and anti-patterns:
+```bash
+npx papermc-skill audit
+```
+
+Query the newest Minecraft & PaperMC releases from the official API:
 ```bash
 npx papermc-skill check-update
 ```
 
-To audit any plugin codebase for exploits, memory leaks, and anti-patterns:
+Browse architectural cheat sheets directly in your terminal:
 ```bash
-npx papermc-skill audit
+npx papermc-skill docs
+```
+
+---
+
+## 🤖 Universal AI Agent Installation
+
+Integrate the skill into your preferred AI agent environment with native workspace rules and global configurations:
+
+```bash
+# Interactive selection menu
+npx papermc-skill install-skill
+
+# Install to ALL supported agents at once
+npx papermc-skill install-skill --all
+
+# Or target specific platforms:
+npx papermc-skill install-skill --agent agy       # Google Antigravity & AGY CLI (~/.gemini/config/skills)
+npx papermc-skill install-skill --agent claude    # Claude Code (~/.claude & workspace CLAUDE.md)
+npx papermc-skill install-skill --agent codex     # OpenAI Codex (~/.codex & workspace CODEX.md)
+npx papermc-skill install-skill --agent cursor    # Cursor (.cursor/rules & .cursorrules)
+npx papermc-skill install-skill --agent deepseek  # DeepSeek Harness (~/.deepseek & DEEPSEEK.md)
+npx papermc-skill install-skill --agent paseo     # Paseo (~/.paseo & .paseo/rules.md)
+npx papermc-skill install-skill --agent pi        # pi.dev (~/.pi & .pi/rules.md)
+npx papermc-skill install-skill --agent windsurf  # Windsurf (.windsurfrules)
 ```
 
+See [**Guide 13: Multi-Agent System & Tooling**](docs/13-multi-agent-system-and-tooling.md) for full configuration details.
+
+---
+
+## ⚡ Overpowered (OP) Code Generators
+
+Scaffold exploit-proof, modern patterns into your plugin with zero boilerplate:
+
+| Command | Generated Artifact | Highlights |
+| :--- | :--- | :--- |
+| `npx papermc-skill generate component-item` | `ModernItemBuilder.java` | MC 1.20.5+ / 1.21+ / 26.x Data Components. Zero NBT, custom model data, food props, glint override. |
+| `npx papermc-skill generate display-entity` | `DisplayHologramEngine.java` | Zero-tick lag TextDisplay & ItemDisplay with smooth client-side JOML Matrix4f interpolation. |
+| `npx papermc-skill generate mace-combat` | `MaceKineticCombatListener.java` | 1.21 Tricky Trials Mace smash physics, height-scaled damage, particle shockwave knockback. |
+| `npx papermc-skill generate menu-gui` | `SafeMenuController.java` | Anti-dupe inventory menu with 200ms click debounce, cursor safety, and drag cancellation. |
+
 ---
 
 ## 💎 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+) |
+| Feature | 💀 Legacy Spigot / Bukkit | ⚡ Modern Paper & Folia (1.21+ / 26.x) |
 | :--- | :--- | :--- |
 | **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. |
+| **Item Data System** | Legacy NBT / Lore hacking | **Data Components (`DataComponentTypes`)**: Type-safe, validated, zero-reflection item mutations. |
+| **Floating Visuals** | Laggy `ArmorStand` entities | **Display Entities (`TextDisplay`, `ItemDisplay`)**: Smooth JOML Matrix4f client interpolation, zero CPU tick overhead. |
+| **Persistent Data** | Raw JSON files / custom lore | **PersistentDataContainer (PDC)**: Native, type-safe data 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
+## 📚 13 Masterclass Technical Guides
 
 Written by developers for developers, covering everything from basic setup to high-throughput concurrency:
 
@@ -83,6 +131,8 @@ Written by developers for developers, covering everything from basic setup to hi
 | **09** | [Custom Items, Abilities & Combat](https://github.com/ardianryan/papermc-skill/blob/main/docs/09-custom-items-and-combat.md) | Raycasting spells (`rayTraceEntities`), particle beam effects, vanilla visual cooldowns, and SFX. |
 | **10** | [Asynchronous Database Storage](https://github.com/ardianryan/papermc-skill/blob/main/docs/10-database-and-storage.md) | SQLite & MySQL HikariCP connection pooling, thread-safe asynchronous DAO pattern with `CompletableFuture`. |
 | **11** | [Security & Exploit Prevention](https://github.com/ardianryan/papermc-skill/blob/main/docs/11-security-and-exploit-prevention.md) | Eliminating dupe glitches, inventory race conditions, PDC tamper verification, numeric/economy validation, and packet DoS defense. |
+| **12** | [Modern Data Components & Display Entities](https://github.com/ardianryan/papermc-skill/blob/main/docs/12-data-components-and-display-entities.md) | Paradigm shift from legacy NBT to DataComponentTypes (1.20.5 - 26.x), JOML Matrix4f transforms, and smooth Display Entity holograms. |
+| **13** | [Multi-Agent System & Universal Tooling](https://github.com/ardianryan/papermc-skill/blob/main/docs/13-multi-agent-system-and-tooling.md) | Complete multi-agent integration guide for Antigravity, Claude Code, Codex, Cursor, DeepSeek, Paseo, and pi.dev. |
 
 ---
 
@@ -119,23 +169,13 @@ cd templates/paper-modern-template
 
 ---
 
-## 🤖 AI Agent Integration
-
-This repository includes a machine-readable coding skill in [`skills/paper-plugin-dev/SKILL.md`](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` | [![NPM Version](https://img.shields.io/npm/v/papermc-skill?color=CB3837)](https://www.npmjs.com/package/papermc-skill) |
 | **GitHub Packages** | `@ardianryan/papermc-skill` | [GitHub Packages Hub](https://github.com/users/ardianryan/packages?repo_name=papermc-skill) |
-| **Release Asset** | `papermc-skill-v1.1.0.zip` | [Latest GitHub Release](https://github.com/ardianryan/papermc-skill/releases/latest) |
+| **Release Asset** | `papermc-skill-v1.2.0.zip` | [Latest GitHub Release](https://github.com/ardianryan/papermc-skill/releases/latest) |
 
 ---