---
name: allaymc-plugin-dev
description: Create, update and troubleshoot AllayMC plugins in Java or other JVM languages. Use when (1) creating a new AllayMC plugin. (2) migrating an existing plugin to AllayMC. (3) troubleshooting an AllayMC plugin.
license: LGPL-2.1
metadata:
  author: AllayMC
---

# AllayMC Plugin Development

## About AllayMC

AllayMC is a third-party server software for Minecraft: Bedrock Edition written in Java. It provides a set of
APIs for plugins to use. AllayMC is broadly divided into the following two modules:

- api: A set of interfaces provided for plugins.
- server: An implementation of the api. Plugins usually don't have access to it.

## About Plugin

Plugins in AllayMC are just like Bukkit plugins, they are loaded by the server when the server starts. Plugins
are used to extend server functionality.

## Workflow for a new plugin

### 1) Initialize the project

- Use the official template at `references/JavaPluginTemplate` If the user haven't initialize the project.
- If the user has already initialized the project, proceed to the next step.

### 2) Initialize Gradle and plugin metadata

Before you begin, ask the user the following questions:

- What is the name of the plugin?
- What is the package name used by the plugin?
- What is the plugin author(s) name?
- What is the website of the plugin?
- What is the allay-api version used for the plugin?

After the user answers the above questions, initialize the project metadata with the collected information.
Before that, determine whether the user is using `JavaPluginTemplate`, which is implemented by determining whether
the current project package name is `org.allaymc.javaplugintemplate`.

#### Case 1: If the project is using `JavaPluginTemplate`:

- Rename package name from `org.allaymc.javaplugintemplate` to the user provided group name.
- Set the project name in `settings.gradle.kts` to the user provided plugin name.
- Update `build.gradle.kts`, solve all the TODOs inside.

#### Case 2: If the project is not using `JavaPluginTemplate`:

- Update `group`, `version` (should start with `0.1.0`), and `description` in `build.gradle.kts`.
- Keep package of the plugin main class aligned with the value of `group` in `build.gradle.kts`.
- Set the Java toolchain to 21 unless the user needs a different version in `build.gradle.kts`.
- If the project is using `AllayGradle` plugin, update the `allay {}` block in `build.gradle.kts`:
  - 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 `plugin.json` per the docs in `references/Allay/docs/tutorials/create-your-first-plugin.md`.

### 3) Implement the plugin entry class

- Create the plugin entry class using plugin name and let it extends `org.allaymc.api.plugin.Plugin`
- Override lifecycle methods in the entry class as needed:
  - `onLoad` which is called before world loading.
  - `onEnable` which is called after world loading.
  - `onDisable` which is called when the server is stopping.
- If reloadable behavior is required, override `isReloadable` and implement `reload`.

### 4) Implement the plugin logic

Understand the user's needs and read the documentation and code marked in the reference map below as needed.

### 5) Build and run

- Use `./gradlew runServer` for local testing when the AllayGradle plugin is configured.
- Use `./gradlew shadowJar` to build the shaded jar.

## Reference map

- Allay documents (read on demand): `references/Allay/docs/tutorials` and `references/Allay/docs/advanced`.
- JavaPluginTemplate: `references/JavaPluginTemplate`
- Allay project source: `references/Allay`
  - Allay API: `references/Allay/api/src/main/java/org/allaymc/api`
  - Allay Server (API Implementation): `references/Allay/server/src/main/java/org/allaymc/server`
- AllayGradle project source: `references/AllayGradle`
  - Usage Guide: `references/AllayGradle/README.md`

## Notes

- AllayMC is multithreaded, and special attention should be paid to multithreaded security issues when writing project code.
- 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.
- Don't overwrite defensive code, such as checking if an object that is explicitly marked as impossible null is null. Produce readable, easy-to-maintain code.