allaymc-plugin-dev

---
name: allaymc-plugin-dev
description: Build, update, and troubleshoot AllayMC plugins in Java or other JVM languages. Use when creating a new AllayMC plugin, migrating an existing plugin to a new Allay API version, wiring commands/events/tasks/config, or setting up Gradle and plugin metadata (plugin.json or AllayGradle plugin block).
license: LGPL-2.1
metadata:
  author: AllayMC
---

# AllayMC Plugin Development

## Overview

Create AllayMC plugins using the official Java template and the Allay API. Keep the workflow aligned with the latest Allay API and docs from the bundled references, and default to the template's Java 21 toolchain unless the user requests otherwise.

## Null-safety policy

AllayMC currently does not use annotations such as JSpecify's @Nullable/@NonNull. Unless a method's Javadoc explicitly states that a parameter or return value may be null, treat it as non-null.

## Workflow

### 1) Pick the starting point

- Prefer the official template at `references/JavaPluginTemplate` for new plugins.
- If updating an existing plugin, diff its `build.gradle.kts` and plugin main class against the template.

### 2) Align Gradle and plugin metadata

- Update `group`, `description`, and `version` in `build.gradle.kts`.
- Keep `group` aligned with the package of the plugin main class.
- Keep the Java toolchain consistent with the template unless the user needs a different version.
- In the `allay {}` block:
  - Set `api` to the target Allay API version.
  - Set `plugin.entrance` to the fully qualified main class (or short suffix as used in the template).
  - Update `authors` and `website`.
- If the project does not use the AllayGradle plugin, create or update `plugin.json` per the docs in `references/Allay/docs/tutorials/create-your-first-plugin.md`.

### 3) Implement the plugin entry class

- Extend `org.allaymc.api.plugin.Plugin`.
- Override lifecycle methods as needed:
  - `onLoad` for lightweight setup.
  - `onEnable` for registrations and runtime wiring.
  - `onDisable` for cleanup.
- Keep the class name and `plugin.entrance`/`plugin.json` entrance consistent.
- If reloadable behavior is required, override `isReloadable` and implement `reload`.
- Reference the base class in `references/Allay/api/src/main/java/org/allaymc/api/plugin/Plugin.java`.

### 4) Add core features (choose only what is needed)

- Commands: follow `references/Allay/docs/tutorials/register-commands.md`.
- Events: follow `references/Allay/docs/tutorials/register-event-listeners.md`.
- Tasks: follow `references/Allay/docs/tutorials/schedule-tasks.md`.
- Config: follow `references/Allay/docs/tutorials/use-config.md`.
- Permissions: follow `references/Allay/docs/tutorials/use-permission.md`.
- i18n: follow `references/Allay/docs/tutorials/use-i18n.md`.
- Forms/UI: follow `references/Allay/docs/tutorials/use-forms.md`.
- Data: follow `references/Allay/docs/tutorials/persistent-data-container.md`.
- Blocks/items: follow `references/Allay/docs/tutorials/block-api.md` and `references/Allay/docs/tutorials/item-api.md`.

### 5) Build and run

- Use `./gradlew runServer` for local testing when the AllayGradle plugin is configured.
- Use `./gradlew shadowJar` to build the shaded jar.
- Copy the jar from `build/libs/*-shaded.jar` into the Allay server `plugins` directory.

### 6) Troubleshoot (only when asked)

- Plugin not loading: verify `plugin.entrance` (or `plugin.json` entrance), `api`/`api_version`, and the jar location.
- API mismatch: update the Gradle `allay.api` version to a valid Allay API release.
- Class not found: confirm the package name matches `group` and the compiled class name.

## Reference map (load on demand)

- Template project: `references/JavaPluginTemplate`
  - `build.gradle.kts` for Gradle + AllayGradle conventions
  - `README.md` for template initialization steps
  - `src/main/java/.../JavaPluginTemplate.java` for lifecycle structure
- AllayGradle: `references/AllayGradle`
  - Gradle plugin sources and configuration patterns
- Allay source and API: `references/Allay`
  - API entry points: `api/src/main/java/org/allaymc/api`
  - Tutorials: `docs/tutorials/*.md`

## Output expectations

- Keep Gradle config, plugin metadata, and main class in sync.
- Target the requested Allay API version and reflect it in Gradle metadata.
- Prefer the template conventions unless the user explicitly wants a custom structure.