[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M74FJ586R436QNFWXEYRFP7S":3,"skill-same:01M74FJ586R436QNFWXEYRFP7S":58},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":6,"ownerDescription":30,"updatedAt":31,"install":32,"resources":45},"01M74FJ586R436QNFWXEYRFP7S","minecraft-plugin-dev",null,"Develop Minecraft server plugins using the Paper\u002FBukkit\u002FSpigot API for Minecraft 26.x (and the 1.21.x line). Handles creating Paper plugins with JavaPlugin, event listeners with @EventHandler, commands, schedulers (sync\u002Fasync\u002FFolia-safe), Persistent Data Container (PDC), Adventure text components, Vault economy integration, BungeeCord\u002FVelocity messaging, plugin.yml and paper-plugin.yml configuration, YAML config management, and Paper-specific enhancement APIs. Targets Paper API 26.2 (Java 25; 1.21.x servers use Java 21) with Gradle (Kotlin DSL). Plugins run server-side only and do not require client installation. Use when creating or modifying Minecraft server plugins, working with Paper\u002FBukkit\u002FSpigot APIs, or developing server-side features involving event handlers, commands, or plugin.yml configuration.","AIKUSAN\u002Fminecraft-agent-skills-bundle","AIKUSAN","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F54048610?v=4","01M74FG91YZ75JDYZ7PNHER2NJ","Lorenz Tazan","01M74FG931PS45HBP26RKEZQDT",12,"MIT","https:\u002F\u002Fgithub.com\u002FAIKUSAN\u002Fminecraft-agent-skills-bundle\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fminecraft-plugin-dev\u002FSKILL.md",[],[],"2026-11-11 15:11:14",false,"---\nname: minecraft-plugin-dev\ndescription: \"Develop Minecraft server plugins using the Paper\u002FBukkit\u002FSpigot API for Minecraft 26.x (and the 1.21.x line). Handles creating Paper plugins with JavaPlugin, event listeners with @EventHandler, commands, schedulers (sync\u002Fasync\u002FFolia-safe), Persistent Data Container (PDC), Adventure text components, Vault economy integration, BungeeCord\u002FVelocity messaging, plugin.yml and paper-plugin.yml configuration, YAML config management, and Paper-specific enhancement APIs. Targets Paper API 26.2 (Java 25; 1.21.x servers use Java 21) with Gradle (Kotlin DSL). Plugins run server-side only and do not require client installation. Use when creating or modifying Minecraft server plugins, working with Paper\u002FBukkit\u002FSpigot APIs, or developing server-side features involving event handlers, commands, or plugin.yml configuration.\"\n---\n\n# Minecraft Plugin Development Skill\n\n## Platform Overview\n\n| Platform | Base API | Notes |\n|----------|----------|-------|\n| **Paper** | Bukkit\u002FSpigot + Paper extensions | Recommended; async chunk loading, Adventure native |\n| **Spigot** | Bukkit + Spigot extensions | Legacy; fewer APIs, slower |\n| **Bukkit** | Base API only | Avoid for new plugins |\n| **Folia** | Paper fork | Region-threaded; requires special scheduler APIs |\n\n> Paper is the recommended target. Paper includes all Bukkit and Spigot APIs plus\n> significant performance improvements and additional APIs.\n\n### Routing Boundaries\n- `Use when`: the target is server-side Paper\u002FBukkit\u002FSpigot plugin behavior with JavaPlugin APIs.\n- `Do not use when`: the task requires client-side installable mods or loader APIs (`minecraft-modding` \u002F `minecraft-multiloader`).\n- `Do not use when`: the task is pure vanilla datapack\u002Fcommand content (`minecraft-datapack` \u002F `minecraft-commands-scripting`).\n- `Do not use when`: the task is a Bedrock add-on or Script API pack (`minecraft-bedrock-addon-dev`).\n- `Do not use when`: the task is installing, configuring or operating an existing plugin (`minecraft-server-admin`, `minecraft-permissions-admin`, `minecraft-essentials-ops`).\n- `Do not use when`: the task is writing automated tests (`minecraft-testing`) or release pipelines (`minecraft-ci-release`).\n\n## Bundled References\n\n- Read `references\u002Fruntime-patterns.md` when the task touches scheduling, Folia support, PDC, Adventure\u002FMiniMessage, YAML config, Vault, or Paper-specific APIs.\n\n---\n\n## Project Setup\n\n### `settings.gradle.kts`\n```kotlin\nrootProject.name = \"my-plugin\"\n```\n\n### `build.gradle.kts`\n```kotlin\nplugins {\n    java\n    id(\"com.gradleup.shadow\") version \"8.3.0\"\n}\n\ngroup = \"com.example\"\nversion = \"1.0.0-SNAPSHOT\"\n\nrepositories {\n    mavenCentral()\n    maven(\"https:\u002F\u002Frepo.papermc.io\u002Frepository\u002Fmaven-public\u002F\")\n    \u002F\u002F For Vault (economy API)\n    maven(\"https:\u002F\u002Fjitpack.io\")\n}\n\ndependencies {\n    compileOnly(\"io.papermc.paper:paper-api:26.2.build.+\")\n    \u002F\u002F Optional: Vault economy\u002Fpermission integration\n    compileOnly(\"com.github.MilkBowl:VaultAPI:1.7\")\n}\n\njava {\n    toolchain.languageVersion.set(JavaLanguageVersion.of(25))\n}\n\ntasks {\n    processResources {\n        \u002F\u002F Substitutes ${version} in plugin.yml with the Gradle project version\n        filesMatching(listOf(\"plugin.yml\", \"paper-plugin.yml\")) {\n            expand(\"version\" to project.version)\n        }\n    }\n    shadowJar {\n        archiveClassifier.set(\"\")\n    }\n    build {\n        dependsOn(shadowJar)\n    }\n}\n```\n\n### `gradle\u002Fwrapper\u002Fgradle-wrapper.properties`\n```properties\ndistributionUrl=https\\:\u002F\u002Fservices.gradle.org\u002Fdistributions\u002Fgradle-8.8-bin.zip\n```\n\n---\n\n## Project Layout\n```\nmy-plugin\u002F\n├── build.gradle.kts\n├── settings.gradle.kts\n├── gradle\u002F\n│   └── wrapper\u002F\n│       └── gradle-wrapper.properties\n└── src\u002Fmain\u002F\n    ├── java\u002Fcom\u002Fexample\u002Fmyplugin\u002F\n    │   ├── MyPlugin.java          ← main class (extends JavaPlugin)\n    │   ├── listeners\u002F\n    │   │   └── PlayerListener.java\n    │   ├── commands\u002F\n    │   │   └── MyCommand.java\n    │   └── managers\u002F\n    │       └── DataManager.java\n    └── resources\u002F\n        ├── plugin.yml\n        ├── paper-plugin.yml      ← optional, Paper-only metadata\n        └── config.yml\n```\n\n---\n\n## Core Files\n\n### `plugin.yml` (Bukkit-compatible default)\n```yaml\nname: MyPlugin\nversion: \"${version}\"\nmain: com.example.myplugin.MyPlugin\ndescription: An example Paper plugin\nauthor: YourName\nwebsite: https:\u002F\u002Fgithub.com\u002Fexample\u002Fmy-plugin\napi-version: '26.2'\n\ncommands:\n  myplugin:\n    description: Main plugin command\n    usage: \u002Fmyplugin \u003Csubcommand>\n    permission: myplugin.use\n    aliases: [mp]\n\npermissions:\n  myplugin.use:\n    description: Allows use of \u002Fmyplugin\n    default: true\n  myplugin.admin:\n    description: Admin access\n    default: op\n```\n\n> Minecraft Java now uses year-based versions (26.1, 26.2, 26.3). Use `api-version: '26.2'`\n> to target Paper 26.2. Older servers on the 1.21 line still use `api-version: '1.21'`\n> or `'1.21.\u003Cpatch>'`.\n> In this repo, the validator accepts `1.21`, positive `1.21.\u003Cpatch>` values, and `26.\u003Cminor>` or\n> `26.\u003Cminor>.\u003Chotfix>` values. A 26.x minor newer than the documented example (`26.2`) is allowed\n> but warned, so new Paper releases do not force an immediate validator edit.\n> Values such as `1.21.0`, `1.21.01`, `1.22` or `26.0` are rejected.\n> Paper 26.x needs Java 25. Paper 26.3 is still beta; confirm the build on https:\u002F\u002Fpapermc.io\u002Fdownloads\u002Fpaper before you pin it.\n\n### `paper-plugin.yml` (Paper-only metadata)\n\nUse `paper-plugin.yml` when you need Paper-specific metadata such as `folia-supported`\nor server\u002Fbootstrap dependency ordering. Keep `plugin.yml` if you must stay portable\nto Bukkit-derived servers that do not understand the Paper-specific file.\n\n```yaml\nname: MyPlugin\nversion: \"${version}\"\nmain: com.example.myplugin.MyPlugin\napi-version: '26.2'\nfolia-supported: true\n\ndependencies:\n    server:\n        Vault:\n            load: BEFORE\n            required: false\n```\n\n### Main Plugin Class\n```java\npackage com.example.myplugin;\n\nimport com.example.myplugin.commands.MyCommand;\nimport com.example.myplugin.listeners.PlayerListener;\nimport org.bukkit.plugin.java.JavaPlugin;\n\npublic final class MyPlugin extends JavaPlugin {\n\n    private static MyPlugin instance;\n\n    @Override\n    public void onEnable() {\n        instance = this;\n        saveDefaultConfig();\n\n        \u002F\u002F Register listeners\n        getServer().getPluginManager().registerEvents(new PlayerListener(this), this);\n\n        \u002F\u002F Register commands\n        var cmd = getCommand(\"myplugin\");\n        if (cmd != null) {\n            cmd.setExecutor(new MyCommand(this));\n            cmd.setTabCompleter(new MyCommand(this));\n        }\n\n        getLogger().info(\"MyPlugin enabled!\");\n    }\n\n    @Override\n    public void onDisable() {\n        getLogger().info(\"MyPlugin disabled.\");\n    }\n\n    public static MyPlugin getInstance() {\n        return instance;\n    }\n}\n```\n\n---\n\n## Event Listeners\n\n```java\npackage com.example.myplugin.listeners;\n\nimport com.example.myplugin.MyPlugin;\nimport net.kyori.adventure.text.Component;\nimport net.kyori.adventure.text.format.NamedTextColor;\nimport org.bukkit.event.EventHandler;\nimport org.bukkit.event.EventPriority;\nimport org.bukkit.event.Listener;\nimport org.bukkit.event.entity.PlayerDeathEvent;\nimport org.bukkit.event.player.PlayerJoinEvent;\nimport org.bukkit.event.player.PlayerQuitEvent;\n\npublic class PlayerListener implements Listener {\n\n    private final MyPlugin plugin;\n\n    public PlayerListener(MyPlugin plugin) {\n        this.plugin = plugin;\n    }\n\n    @EventHandler(priority = EventPriority.NORMAL, ignoreCancelled = true)\n    public void onPlayerJoin(PlayerJoinEvent event) {\n        event.joinMessage(\n            Component.text(event.getPlayer().getName() + \" joined!\", NamedTextColor.GREEN)\n        );\n    }\n\n    @EventHandler\n    public void onPlayerQuit(PlayerQuitEvent event) {\n        event.quitMessage(\n            Component.text(event.getPlayer().getName() + \" left.\", NamedTextColor.YELLOW)\n        );\n    }\n\n    @EventHandler(ignoreCancelled = true)\n    public void onPlayerDeath(PlayerDeathEvent event) {\n        \u002F\u002F Modify death message using Adventure components\n        event.deathMessage(\n            Component.text(\"☠ \", NamedTextColor.RED)\n                .append(Component.text(event.getPlayer().getName(), NamedTextColor.WHITE))\n                .append(Component.text(\" died!\", NamedTextColor.RED))\n        );\n    }\n}\n```\n\n### EventPriority order\n`LOWEST → LOW → NORMAL → HIGH → HIGHEST → MONITOR`  \nUse `MONITOR` for logging only (never modify outcome). Use `ignoreCancelled = true` unless\nyou have a specific reason to handle cancelled events.\n\n### Cancellable events\n```java\n@EventHandler\npublic void onBlockBreak(BlockBreakEvent event) {\n    if (event.getPlayer().hasPermission(\"myplugin.break.deny\")) {\n        event.setCancelled(true);\n        event.getPlayer().sendMessage(Component.text(\"You cannot break blocks!\", NamedTextColor.RED));\n    }\n}\n```\n\n---\n\n## Commands\n\n```java\npackage com.example.myplugin.commands;\n\nimport com.example.myplugin.MyPlugin;\nimport net.kyori.adventure.text.Component;\nimport net.kyori.adventure.text.format.NamedTextColor;\nimport org.bukkit.command.Command;\nimport org.bukkit.command.CommandExecutor;\nimport org.bukkit.command.CommandSender;\nimport org.bukkit.command.TabCompleter;\nimport org.bukkit.entity.Player;\nimport org.jetbrains.annotations.NotNull;\nimport org.jetbrains.annotations.Nullable;\n\nimport java.util.List;\n\npublic class MyCommand implements CommandExecutor, TabCompleter {\n\n    private final MyPlugin plugin;\n\n    public MyCommand(MyPlugin plugin) {\n        this.plugin = plugin;\n    }\n\n    @Override\n    public boolean onCommand(@NotNull CommandSender sender, @NotNull Command command,\n                             @NotNull String label, @NotNull String[] args) {\n        if (!(sender instanceof Player player)) {\n            sender.sendMessage(Component.text(\"Only players can use this command.\", NamedTextColor.RED));\n            return true;\n        }\n\n        if (!player.hasPermission(\"myplugin.use\")) {\n            player.sendMessage(Component.text(\"No permission.\", NamedTextColor.RED));\n            return true;\n        }\n\n        if (args.length == 0) {\n            player.sendMessage(Component.text(\"Usage: \u002Fmyplugin \u003Creload|info>\", NamedTextColor.YELLOW));\n            return true;\n        }\n\n        return switch (args[0].toLowerCase()) {\n            case \"reload\" -> {\n                plugin.reloadConfig();\n                player.sendMessage(Component.text(\"Config reloaded.\", NamedTextColor.GREEN));\n                yield true;\n            }\n            case \"info\" -> {\n                player.sendMessage(Component.text(\"Version: \" + plugin.getDescription().getVersion(), NamedTextColor.AQUA));\n                yield true;\n            }\n            default -> {\n                player.sendMessage(Component.text(\"Unknown subcommand.\", NamedTextColor.RED));\n                yield false;\n            }\n        };\n    }\n\n    @Override\n    public @Nullable List\u003CString> onTabComplete(@NotNull CommandSender sender, @NotNull Command command,\n                                                @NotNull String label, @NotNull String[] args) {\n        if (args.length == 1) {\n            return List.of(\"reload\", \"info\").stream()\n                .filter(s -> s.startsWith(args[0].toLowerCase()))\n                .toList();\n        }\n        return List.of();\n    }\n}\n```\n\n---\n\n## Schedulers\n\nFor classic Paper plugins, `BukkitScheduler` is still fine. If you claim Folia support,\nroute player, entity, region, global, and async work through the matching Folia-aware\nscheduler. Keep scheduling behind a small project-local interface when one plugin must\nsupport both Paper and Folia.\n\nSee `references\u002Fruntime-patterns.md` for copy-ready sync, async, cancelable, and\nFolia-safe scheduler examples.\n\n---\n\n## Persistent Data Container (PDC)\n\nPDC stores arbitrary data on any `PersistentDataHolder` (players, entities, items, chunks).\nData is saved with the world and persists across restarts.\n\nCreate `NamespacedKey` instances once, keep data types stable after release, and use\nPDC for small metadata rather than large datasets. Prefer config files or a database\nfor large or query-heavy plugin state.\n\nSee `references\u002Fruntime-patterns.md` for player, item, chunk, and world PDC examples.\n\n---\n\n## Adventure Text Components\n\nPaper uses [Adventure](https:\u002F\u002Fdocs.advntr.dev\u002F) natively for all text. No legacy chat colors.\nUse `Component` builders for code-owned messages and MiniMessage for config-driven\nmessages. Avoid legacy `ChatColor` unless the target project already depends on it\nfor compatibility.\n\nSee `references\u002Fruntime-patterns.md` for simple messages, hover\u002Fclick events,\nMiniMessage parsing, titles, and action bars.\n\n---\n\n## Configuration (YAML)\n\n### `src\u002Fmain\u002Fresources\u002Fconfig.yml`\n```yaml\n# Default config\nsettings:\n  max-players: 20\n  welcome-message: \"\u003Cgreen>Welcome to the server!\"\n  cooldown-seconds: 30\n\ndatabase:\n  host: localhost\n  port: 3306\n  name: myplugin_db\n```\n\n### Accessing config values\nCall `saveDefaultConfig()` in `onEnable()`, provide explicit defaults when reading\nvalues, and validate config shape before starting long-running tasks.\n\n### Custom config file\nUse custom YAML files only when separating user config from mutable plugin data is\nworth the extra file handling. Keep blocking disk writes off hot event paths.\n\nSee `references\u002Fruntime-patterns.md` for config read\u002Fwrite and custom YAML examples.\n\n---\n\n## Vault Integration (Economy \u002F Permissions)\n\nDeclare Vault as `compileOnly`, soft-depend on it in plugin metadata, and disable\neconomy features cleanly when the service provider is unavailable. Never assume a\nVault-compatible economy plugin is installed just because Vault itself is present.\n\nSee `references\u002Fruntime-patterns.md` for a minimal economy setup and charge example.\n\n---\n\n## Paper-Specific APIs\n\nUse Paper APIs when they remove main-thread blocking or simplify Adventure-native\nbehavior. Keep optional plugin integrations behind presence checks and metadata\nsoft-dependencies.\n\nSee `references\u002Fruntime-patterns.md` for async chunk loading, custom item meta,\nprofile lookup, and protection-plugin integration examples.\n\n---\n\n## Common Tasks Checklist\n\n### Creating a new event listener\n- [ ] Create class implementing `Listener`\n- [ ] Annotate methods with `@EventHandler`\n- [ ] Call `getServer().getPluginManager().registerEvents(listener, plugin)` in `onEnable()`\n- [ ] Add `ignoreCancelled = true` unless you need cancelled events\n\n### Adding a new command\n- [ ] Define command in `plugin.yml` under `commands:`\n- [ ] Create executor class implementing `CommandExecutor`\n- [ ] (Optional) implement `TabCompleter` for autocomplete\n- [ ] Register with `getCommand(\"name\").setExecutor(new MyExecutor())`\n\n### Saving plugin data\n- [ ] For simple values: use `config.yml` via `getConfig()` \u002F `saveConfig()`\n- [ ] For per-entity data: use PDC with a `NamespacedKey`\n- [ ] For large datasets: use async scheduler + file I\u002FO or a database\n\n### Scheduling a repeating task\n- [ ] Determine if task needs main thread (use `runTaskTimer`) or is I\u002FO (use `runTaskTimerAsynchronously`)\n- [ ] Store the `BukkitTask` reference so you can cancel in `onDisable()`\n- [ ] Cancel all tasks in `onDisable()` or use `getServer().getScheduler().cancelTasks(plugin)`\n\n---\n\n## Build, Validate, and Run\n\n1. Build the plugin JAR:\n   ```bash\n   .\u002Fgradlew shadowJar\n   # Output: build\u002Flibs\u002Fmy-plugin-1.0.0-SNAPSHOT.jar\n   ```\n2. Run the bundled validator to catch config and layout errors:\n   ```bash\n   .\u002Fscripts\u002Fvalidate-plugin-layout.sh --root \u002Fpath\u002Fto\u002Fplugin-project\n   # Strict mode treats warnings as failures:\n   .\u002Fscripts\u002Fvalidate-plugin-layout.sh --root \u002Fpath\u002Fto\u002Fplugin-project --strict\n   ```\n3. Fix any reported errors and re-run until clean.\n4. Deploy: copy JAR to `server\u002Fplugins\u002F` and restart, or use the dev server:\n   ```bash\n   .\u002Fgradlew runServer\n   ```\n\nThe validator checks:\n- `plugin.yml` required keys (`name`, `version`, `main`, `api-version`) and repo-supported `1.21`, positive `1.21.\u003Cpatch>` and `26.\u003Cminor>[.\u003Chotfix>]` `api-version` values, with warnings for versions newer than the repo's current example\n- Main class path exists and extends `JavaPlugin`\n- `\u002Freload` anti-pattern detection in source snippets\n\n---\n\n## References\n\n- Paper API Javadoc: https:\u002F\u002Fjd.papermc.io\u002Fpaper\u002F\n- Paper Dev Docs: https:\u002F\u002Fdocs.papermc.io\u002Fpaper\u002Fdev\u002Fgetting-started\u002F\n- Adventure (text API): https:\u002F\u002Fdocs.advntr.dev\u002F\n- MiniMessage format: https:\u002F\u002Fdocs.advntr.dev\u002Fminimessage\u002Fformat.html\n- Vault API: https:\u002F\u002Fgithub.com\u002FMilkBowl\u002FVaultAPI\n- Bukkit API Javadoc: https:\u002F\u002Fjavadoc.io\u002Fdoc\u002Forg.bukkit\u002Fbukkit\u002F\n- run-task Gradle plugin: https:\u002F\u002Fgithub.com\u002Fjpenilla\u002Frun-task\n","# Minecraft Plugin Development Skill\n\n## Platform Overview\n\n| Platform | Base API | Notes |\n|----------|----------|-------|\n| **Paper** | Bukkit\u002FSpigot + Paper extensions | Recommended; async chunk loading, Adventure native |\n| **Spigot** | Bukkit + Spigot extensions | Legacy; fewer APIs, slower |\n| **Bukkit** | Base API only | Avoid for new plugins |\n| **Folia** | Paper fork | Region-threaded; requires special scheduler APIs |\n\n> Paper is the recommended target. Paper includes all Bukkit and Spigot APIs plus\n> significant performance improvements and additional APIs.\n\n### Routing Boundaries\n- `Use when`: the target is server-side Paper\u002FBukkit\u002FSpigot plugin behavior with JavaPlugin APIs.\n- `Do not use when`: the task requires client-side installable mods or loader APIs (`minecraft-modding` \u002F `minecraft-multiloader`).\n- `Do not use when`: the task is pure vanilla datapack\u002Fcommand content (`minecraft-datapack` \u002F `minecraft-commands-scripting`).\n- `Do not use when`: the task is a Bedrock add-on or Script API pack (`minecraft-bedrock-addon-dev`).\n- `Do not use when`: the task is installing, configuring or operating an existing plugin (`minecraft-server-admin`, `minecraft-permissions-admin`, `minecraft-essentials-ops`).\n- `Do not use when`: the task is writing automated tests (`minecraft-testing`) or release pipelines (`minecraft-ci-release`).\n\n## Bundled References\n\n- Read `references\u002Fruntime-patterns.md` when the task touches scheduling, Folia support, PDC, Adventure\u002FMiniMessage, YAML config, Vault, or Paper-specific APIs.\n\n---\n\n## Project Setup\n\n### `settings.gradle.kts`\n```kotlin\nrootProject.name = \"my-plugin\"\n```\n\n### `build.gradle.kts`\n```kotlin\nplugins {\n    java\n    id(\"com.gradleup.shadow\") version \"8.3.0\"\n}\n\ngroup = \"com.example\"\nversion = \"1.0.0-SNAPSHOT\"\n\nrepositories {\n    mavenCentral()\n    maven(\"https:\u002F\u002Frepo.papermc.io\u002Frepository\u002Fmaven-public\u002F\")\n    \u002F\u002F For Vault (economy API)\n    maven(\"https:\u002F\u002Fjitpack.io\")\n}\n\ndependencies {\n    compileOnly(\"io.papermc.paper:paper-api:26.2.build.+\")\n    \u002F\u002F Optional: Vault economy\u002Fpermission integration\n    compileOnly(\"com.github.MilkBowl:VaultAPI:1.7\")\n}\n\njava {\n    toolchain.languageVersion.set(JavaLanguageVersion.of(25))\n}\n\ntasks {\n    processResources {\n        \u002F\u002F Substitutes ${version} in plugin.yml with the Gradle project version\n        filesMatching(listOf(\"plugin.yml\", \"paper-plugin.yml\")) {\n            expand(\"version\" to project.version)\n        }\n    }\n    shadowJar {\n        archiveClassifier.set(\"\")\n    }\n    build {\n        dependsOn(shadowJar)\n    }\n}\n```\n\n### `gradle\u002Fwrapper\u002Fgradle-wrapper.properties`\n```properties\ndistributionUrl=https\\:\u002F\u002Fservices.gradle.org\u002Fdistributions\u002Fgradle-8.8-bin.zip\n```\n\n---\n\n## Project Layout\n```\nmy-plugin\u002F\n├── build.gradle.kts\n├── settings.gradle.kts\n├── gradle\u002F\n│   └── wrapper\u002F\n│       └── gradle-wrapper.properties\n└── src\u002Fmain\u002F\n    ├── java\u002Fcom\u002Fexample\u002Fmyplugin\u002F\n    │   ├── MyPlugin.java          ← main class (extends JavaPlugin)\n    │   ├── listeners\u002F\n    │   │   └── PlayerListener.java\n    │   ├── commands\u002F\n    │   │   └── MyCommand.java\n    │   └── managers\u002F\n    │       └── DataManager.java\n    └── resources\u002F\n        ├── plugin.yml\n        ├── paper-plugin.yml      ← optional, Paper-only metadata\n        └── config.yml\n```\n\n---\n\n## Core Files\n\n### `plugin.yml` (Bukkit-compatible default)\n```yaml\nname: MyPlugin\nversion: \"${version}\"\nmain: com.example.myplugin.MyPlugin\ndescription: An example Paper plugin\nauthor: YourName\nwebsite: https:\u002F\u002Fgithub.com\u002Fexample\u002Fmy-plugin\napi-version: '26.2'\n\ncommands:\n  myplugin:\n    description: Main plugin command\n    usage: \u002Fmyplugin \u003Csubcommand>\n    permission: myplugin.use\n    aliases: [mp]\n\npermissions:\n  myplugin.use:\n    description: Allows use of \u002Fmyplugin\n    default: true\n  myplugin.admin:\n    description: Admin access\n    default: op\n```\n\n> Minecraft Java now uses year-based versions (26.1, 26.2, 26.3). Use `api-version: '26.2'`\n> to target Paper 26.2. Older servers on the 1.21 line still use `api-version: '1.21'`\n> or `'1.21.\u003Cpatch>'`.\n> In this repo, the validator accepts `1.21`, positive `1.21.\u003Cpatch>` values, and `26.\u003Cminor>` or\n> `26.\u003Cminor>.\u003Chotfix>` values. A 26.x minor newer than the documented example (`26.2`) is allowed\n> but warned, so new Paper releases do not force an immediate validator edit.\n> Values such as `1.21.0`, `1.21.01`, `1.22` or `26.0` are rejected.\n> Paper 26.x needs Java 25. Paper 26.3 is still beta; confirm the build on https:\u002F\u002Fpapermc.io\u002Fdownloads\u002Fpaper before you pin it.\n\n### `paper-plugin.yml` (Paper-only metadata)\n\nUse `paper-plugin.yml` when you need Paper-specific metadata such as `folia-supported`\nor server\u002Fbootstrap dependency ordering. Keep `plugin.yml` if you must stay portable\nto Bukkit-derived servers that do not understand the Paper-specific file.\n\n```yaml\nname: MyPlugin\nversion: \"${version}\"\nmain: com.example.myplugin.MyPlugin\napi-version: '26.2'\nfolia-supported: true\n\ndependencies:\n    server:\n        Vault:\n            load: BEFORE\n            required: false\n```\n\n### Main Plugin Class\n```java\npackage com.example.myplugin;\n\nimport com.example.myplugin.commands.MyCommand;\nimport com.example.myplugin.listeners.PlayerListener;\nimport org.bukkit.plugin.java.JavaPlugin;\n\npublic final class MyPlugin extends JavaPlugin {\n\n    private static MyPlugin instance;\n\n    @Override\n    public void onEnable() {\n        instance = this;\n        saveDefaultConfig();\n\n        \u002F\u002F Register listeners\n        getServer().getPluginManager().registerEvents(new PlayerListener(this), this);\n\n        \u002F\u002F Register commands\n        var cmd = getCommand(\"myplugin\");\n        if (cmd != null) {\n            cmd.setExecutor(new MyCommand(this));\n            cmd.setTabCompleter(new MyCommand(this));\n        }\n\n        getLogger().info(\"MyPlugin enabled!\");\n    }\n\n    @Override\n    public void onDisable() {\n        getLogger().info(\"MyPlugin disabled.\");\n    }\n\n    public static MyPlugin getInstance() {\n        return instance;\n    }\n}\n```\n\n---\n\n## Event Listeners\n\n```java\npackage com.example.myplugin.listeners;\n\nimport com.example.myplugin.MyPlugin;\nimport net.kyori.adventure.text.Component;\nimport net.kyori.adventure.text.format.NamedTextColor;\nimport org.bukkit.event.EventHandler;\nimport org.bukkit.event.EventPriority;\nimport org.bukkit.event.Listener;\nimport org.bukkit.event.entity.PlayerDeathEvent;\nimport org.bukkit.event.player.PlayerJoinEvent;\nimport org.bukkit.event.player.PlayerQuitEvent;\n\npublic class PlayerListener implements Listener {\n\n    private final MyPlugin plugin;\n\n    public PlayerListener(MyPlugin plugin) {\n        this.plugin = plugin;\n    }\n\n    @EventHandler(priority = EventPriority.NORMAL, ignoreCancelled = true)\n    public void onPlayerJoin(PlayerJoinEvent event) {\n        event.joinMessage(\n            Component.text(event.getPlayer().getName() + \" joined!\", NamedTextColor.GREEN)\n        );\n    }\n\n    @EventHandler\n    public void onPlayerQuit(PlayerQuitEvent event) {\n        event.quitMessage(\n            Component.text(event.getPlayer().getName() + \" left.\", NamedTextColor.YELLOW)\n        );\n    }\n\n    @EventHandler(ignoreCancelled = true)\n    public void onPlayerDeath(PlayerDeathEvent event) {\n        \u002F\u002F Modify death message using Adventure components\n        event.deathMessage(\n            Component.text(\"☠ \", NamedTextColor.RED)\n                .append(Component.text(event.getPlayer().getName(), NamedTextColor.WHITE))\n                .append(Component.text(\" died!\", NamedTextColor.RED))\n        );\n    }\n}\n```\n\n### EventPriority order\n`LOWEST → LOW → NORMAL → HIGH → HIGHEST → MONITOR`  \nUse `MONITOR` for logging only (never modify outcome). Use `ignoreCancelled = true` unless\nyou have a specific reason to handle cancelled events.\n\n### Cancellable events\n```java\n@EventHandler\npublic void onBlockBreak(BlockBreakEvent event) {\n    if (event.getPlayer().hasPermission(\"myplugin.break.deny\")) {\n        event.setCancelled(true);\n        event.getPlayer().sendMessage(Component.text(\"You cannot break blocks!\", NamedTextColor.RED));\n    }\n}\n```\n\n---\n\n## Commands\n\n```java\npackage com.example.myplugin.commands;\n\nimport com.example.myplugin.MyPlugin;\nimport net.kyori.adventure.text.Component;\nimport net.kyori.adventure.text.format.NamedTextColor;\nimport org.bukkit.command.Command;\nimport org.bukkit.command.CommandExecutor;\nimport org.bukkit.command.CommandSender;\nimport org.bukkit.command.TabCompleter;\nimport org.bukkit.entity.Player;\nimport org.jetbrains.annotations.NotNull;\nimport org.jetbrains.annotations.Nullable;\n\nimport java.util.List;\n\npublic class MyCommand implements CommandExecutor, TabCompleter {\n\n    private final MyPlugin plugin;\n\n    public MyCommand(MyPlugin plugin) {\n        this.plugin = plugin;\n    }\n\n    @Override\n    public boolean onCommand(@NotNull CommandSender sender, @NotNull Command command,\n                             @NotNull String label, @NotNull String[] args) {\n        if (!(sender instanceof Player player)) {\n            sender.sendMessage(Component.text(\"Only players can use this command.\", NamedTextColor.RED));\n            return true;\n        }\n\n        if (!player.hasPermission(\"myplugin.use\")) {\n            player.sendMessage(Component.text(\"No permission.\", NamedTextColor.RED));\n            return true;\n        }\n\n        if (args.length == 0) {\n            player.sendMessage(Component.text(\"Usage: \u002Fmyplugin \u003Creload|info>\", NamedTextColor.YELLOW));\n            return true;\n        }\n\n        return switch (args[0].toLowerCase()) {\n            case \"reload\" -> {\n                plugin.reloadConfig();\n                player.sendMessage(Component.text(\"Config reloaded.\", NamedTextColor.GREEN));\n                yield true;\n            }\n            case \"info\" -> {\n                player.sendMessage(Component.text(\"Version: \" + plugin.getDescription().getVersion(), NamedTextColor.AQUA));\n                yield true;\n            }\n            default -> {\n                player.sendMessage(Component.text(\"Unknown subcommand.\", NamedTextColor.RED));\n                yield false;\n            }\n        };\n    }\n\n    @Override\n    public @Nullable List\u003CString> onTabComplete(@NotNull CommandSender sender, @NotNull Command command,\n                                                @NotNull String label, @NotNull String[] args) {\n        if (args.length == 1) {\n            return List.of(\"reload\", \"info\").stream()\n                .filter(s -> s.startsWith(args[0].toLowerCase()))\n                .toList();\n        }\n        return List.of();\n    }\n}\n```\n\n---\n\n## Schedulers\n\nFor classic Paper plugins, `BukkitScheduler` is still fine. If you claim Folia support,\nroute player, entity, region, global, and async work through the matching Folia-aware\nscheduler. Keep scheduling behind a small project-local interface when one plugin must\nsupport both Paper and Folia.\n\nSee `references\u002Fruntime-patterns.md` for copy-ready sync, async, cancelable, and\nFolia-safe scheduler examples.\n\n---\n\n## Persistent Data Container (PDC)\n\nPDC stores arbitrary data on any `PersistentDataHolder` (players, entities, items, chunks).\nData is saved with the world and persists across restarts.\n\nCreate `NamespacedKey` instances once, keep data types stable after release, and use\nPDC for small metadata rather than large datasets. Prefer config files or a database\nfor large or query-heavy plugin state.\n\nSee `references\u002Fruntime-patterns.md` for player, item, chunk, and world PDC examples.\n\n---\n\n## Adventure Text Components\n\nPaper uses [Adventure](https:\u002F\u002Fdocs.advntr.dev\u002F) natively for all text. No legacy chat colors.\nUse `Component` builders for code-owned messages and MiniMessage for config-driven\nmessages. Avoid legacy `ChatColor` unless the target project already depends on it\nfor compatibility.\n\nSee `references\u002Fruntime-patterns.md` for simple messages, hover\u002Fclick events,\nMiniMessage parsing, titles, and action bars.\n\n---\n\n## Configuration (YAML)\n\n### `src\u002Fmain\u002Fresources\u002Fconfig.yml`\n```yaml\n# Default config\nsettings:\n  max-players: 20\n  welcome-message: \"\u003Cgreen>Welcome to the server!\"\n  cooldown-seconds: 30\n\ndatabase:\n  host: localhost\n  port: 3306\n  name: myplugin_db\n```\n\n### Accessing config values\nCall `saveDefaultConfig()` in `onEnable()`, provide explicit defaults when reading\nvalues, and validate config shape before starting long-running tasks.\n\n### Custom config file\nUse custom YAML files only when separating user config from mutable plugin data is\nworth the extra file handling. Keep blocking disk writes off hot event paths.\n\nSee `references\u002Fruntime-patterns.md` for config read\u002Fwrite and custom YAML examples.\n\n---\n\n## Vault Integration (Economy \u002F Permissions)\n\nDeclare Vault as `compileOnly`, soft-depend on it in plugin metadata, and disable\neconomy features cleanly when the service provider is unavailable. Never assume a\nVault-compatible economy plugin is installed just because Vault itself is present.\n\nSee `references\u002Fruntime-patterns.md` for a minimal economy setup and charge example.\n\n---\n\n## Paper-Specific APIs\n\nUse Paper APIs when they remove main-thread blocking or simplify Adventure-native\nbehavior. Keep optional plugin integrations behind presence checks and metadata\nsoft-dependencies.\n\nSee `references\u002Fruntime-patterns.md` for async chunk loading, custom item meta,\nprofile lookup, and protection-plugin integration examples.\n\n---\n\n## Common Tasks Checklist\n\n### Creating a new event listener\n- [ ] Create class implementing `Listener`\n- [ ] Annotate methods with `@EventHandler`\n- [ ] Call `getServer().getPluginManager().registerEvents(listener, plugin)` in `onEnable()`\n- [ ] Add `ignoreCancelled = true` unless you need cancelled events\n\n### Adding a new command\n- [ ] Define command in `plugin.yml` under `commands:`\n- [ ] Create executor class implementing `CommandExecutor`\n- [ ] (Optional) implement `TabCompleter` for autocomplete\n- [ ] Register with `getCommand(\"name\").setExecutor(new MyExecutor())`\n\n### Saving plugin data\n- [ ] For simple values: use `config.yml` via `getConfig()` \u002F `saveConfig()`\n- [ ] For per-entity data: use PDC with a `NamespacedKey`\n- [ ] For large datasets: use async scheduler + file I\u002FO or a database\n\n### Scheduling a repeating task\n- [ ] Determine if task needs main thread (use `runTaskTimer`) or is I\u002FO (use `runTaskTimerAsynchronously`)\n- [ ] Store the `BukkitTask` reference so you can cancel in `onDisable()`\n- [ ] Cancel all tasks in `onDisable()` or use `getServer().getScheduler().cancelTasks(plugin)`\n\n---\n\n## Build, Validate, and Run\n\n1. Build the plugin JAR:\n   ```bash\n   .\u002Fgradlew shadowJar\n   # Output: build\u002Flibs\u002Fmy-plugin-1.0.0-SNAPSHOT.jar\n   ```\n2. Run the bundled validator to catch config and layout errors:\n   ```bash\n   .\u002Fscripts\u002Fvalidate-plugin-layout.sh --root \u002Fpath\u002Fto\u002Fplugin-project\n   # Strict mode treats warnings as failures:\n   .\u002Fscripts\u002Fvalidate-plugin-layout.sh --root \u002Fpath\u002Fto\u002Fplugin-project --strict\n   ```\n3. Fix any reported errors and re-run until clean.\n4. Deploy: copy JAR to `server\u002Fplugins\u002F` and restart, or use the dev server:\n   ```bash\n   .\u002Fgradlew runServer\n   ```\n\nThe validator checks:\n- `plugin.yml` required keys (`name`, `version`, `main`, `api-version`) and repo-supported `1.21`, positive `1.21.\u003Cpatch>` and `26.\u003Cminor>[.\u003Chotfix>]` `api-version` values, with warnings for versions newer than the repo's current example\n- Main class path exists and extends `JavaPlugin`\n- `\u002Freload` anti-pattern detection in source snippets\n\n---\n\n## References\n\n- Paper API Javadoc: https:\u002F\u002Fjd.papermc.io\u002Fpaper\u002F\n- Paper Dev Docs: https:\u002F\u002Fdocs.papermc.io\u002Fpaper\u002Fdev\u002Fgetting-started\u002F\n- Adventure (text API): https:\u002F\u002Fdocs.advntr.dev\u002F\n- MiniMessage format: https:\u002F\u002Fdocs.advntr.dev\u002Fminimessage\u002Fformat.html\n- Vault API: https:\u002F\u002Fgithub.com\u002FMilkBowl\u002FVaultAPI\n- Bukkit API Javadoc: https:\u002F\u002Fjavadoc.io\u002Fdoc\u002Forg.bukkit\u002Fbukkit\u002F\n- run-task Gradle plugin: https:\u002F\u002Fgithub.com\u002Fjpenilla\u002Frun-task\n",{"name":5,"description":7},"main","6fdc6b3043932f6cec4d0a2d51630b19d220dc0d",".agents\u002Fskills\u002Fminecraft-plugin-dev",1,"https:\u002F\u002Fgithub.com\u002FAIKUSAN\u002Fminecraft-agent-skills-bundle","https:\u002F\u002Fgithub.com\u002FAIKUSAN","Creating virtual worlds, one line of code at a time.","2026-10-03 22:21:47",{"source":8,"skillName":5,"commands":33,"prompt":43,"zipAvailable":44},[34,37,40],{"tool":35,"command":36},"npx","npx skills add AIKUSAN\u002Fminecraft-agent-skills-bundle --skill minecraft-plugin-dev",{"tool":38,"command":39},"bunx","bunx skills add AIKUSAN\u002Fminecraft-agent-skills-bundle --skill minecraft-plugin-dev",{"tool":41,"command":42},"pnpm","pnpm dlx skills add AIKUSAN\u002Fminecraft-agent-skills-bundle --skill minecraft-plugin-dev","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FAIKUSAN\u002Fminecraft-agent-skills-bundle\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fminecraft-plugin-dev\u002FSKILL.md",true,[46,52],{"path":47,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":50,"sourceHtmlUrl":51},"references\u002Fruntime-patterns.md","REFERENCE","参考文档",7695,"https:\u002F\u002Fgithub.com\u002FAIKUSAN\u002Fminecraft-agent-skills-bundle\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fminecraft-plugin-dev\u002Freferences\u002Fruntime-patterns.md",{"path":53,"resourceType":54,"resourceTypeDesc":55,"sizeBytes":56,"sourceHtmlUrl":57},"scripts\u002Fvalidate-plugin-layout.sh","SCRIPT","脚本",5699,"https:\u002F\u002Fgithub.com\u002FAIKUSAN\u002Fminecraft-agent-skills-bundle\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fminecraft-plugin-dev\u002Fscripts\u002Fvalidate-plugin-layout.sh",[59,66,72,78,84,90],{"skillNo":60,"name":61,"nameZh":6,"description":62,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":63,"categories":64,"keywords":65,"publishedAt":19},"01M74FXYYEC9NE1YFJC891WFT2","minecraft-ci-release","Fixture with valid workflow YAML but a warning-only secrets section.","https:\u002F\u002Fgithub.com\u002FAIKUSAN\u002Fminecraft-agent-skills-bundle\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fvalidators\u002Fci-release\u002Fwarn-only\u002FSKILL.md",[],[],{"skillNo":67,"name":68,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":69,"categories":70,"keywords":71,"publishedAt":19},"01M74FXXD5F0J0VA58R53Z8CA3","valid","https:\u002F\u002Fgithub.com\u002FAIKUSAN\u002Fminecraft-agent-skills-bundle\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fvalidators\u002Fci-release\u002Fvalid\u002FSKILL.md",[],[],{"skillNo":73,"name":74,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":19},"01M74FXVT401WRMHEMCPJKA89X","non-workflow-yaml","https:\u002F\u002Fgithub.com\u002FAIKUSAN\u002Fminecraft-agent-skills-bundle\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fvalidators\u002Fci-release\u002Fnon-workflow-yaml\u002FSKILL.md",[],[],{"skillNo":79,"name":61,"nameZh":6,"description":80,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":81,"categories":82,"keywords":83,"publishedAt":19},"01M74FXTBGQGEPGMX81DFY7FY9","Fixture with valid multiline flow collections in workflow YAML.","https:\u002F\u002Fgithub.com\u002FAIKUSAN\u002Fminecraft-agent-skills-bundle\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fvalidators\u002Fci-release\u002Fmultiline-flow\u002FSKILL.md",[],[],{"skillNo":85,"name":86,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":19},"01M74FXSAW6GDZ3J3S9FBGC1D6","invalid","https:\u002F\u002Fgithub.com\u002FAIKUSAN\u002Fminecraft-agent-skills-bundle\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fvalidators\u002Fci-release\u002Finvalid\u002FSKILL.md",[],[],{"skillNo":91,"name":61,"nameZh":6,"description":92,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":93,"categories":94,"keywords":95,"publishedAt":19},"01M74FXQRKYD2DDQDN0HR1TE10","Fixture with malformed workflow YAML.","https:\u002F\u002Fgithub.com\u002FAIKUSAN\u002Fminecraft-agent-skills-bundle\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fvalidators\u002Fci-release\u002Finvalid-yaml\u002FSKILL.md",[],[]]