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.