Getting started

Addon developer

Alpha API

AbstractMenus 2.0 is in alpha. The API surface may change before the stable release. Pin a specific compileOnly version in your build to avoid breaking on a fresh fetch.

AbstractMenus 2.0 ships an SPI: addons register custom actions, rules, item properties, activators, catalogs, and provider handlers (economy, permissions, levels, placeholders, skins) at runtime. Same SPI the built-in types use.

There are two ways to deliver an addon. Pick one:

Path 1 — AM-loaded addon A jar with addon.conf. Drops into plugins/AbstractMenus/addons/, loaded by AbstractMenus.

Path 2 — plugin-as-addon A standard Bukkit plugin. Drops into plugins/, loaded by Bukkit.

The pages below cover the API surface itself. The addons page covers delivery: which path to pick, manifest format, lifecycle.

Add the API to your build

The AbstractMenus API is published on GitHub Packages and built per release on JitPack.

Note

JitPack is anonymous-pull. GitHub Packages requires a Personal Access Token with the read:packages scope, even for public packages — that’s a GitHub limitation, not ours. If you have a strong reason to use GH Packages (e.g. corporate proxy that allowlists *.github.com), see the auth setup at the bottom of this page. Otherwise, JitPack.

Gradle (Kotlin DSL)

build.gradle.kts

repositories {
    maven("https://jitpack.io")
}

dependencies {
    compileOnly("com.github.AbstractMenus:minecraft-plugin:2.0.0-alpha.2")
}

Gradle (Groovy)

build.gradle

repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    compileOnly 'com.github.AbstractMenus:minecraft-plugin:2.0.0-alpha.2'
}

Maven

pom.xml

<repositories>
  <repository>
    <id>jitpack</id>
    <url>https://jitpack.io</url>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>com.github.AbstractMenus</groupId>
    <artifactId>minecraft-plugin</artifactId>
    <version>2.0.0-alpha.2</version>
    <scope>provided</scope>
  </dependency>
</dependencies>

The artifactId is minecraft-plugin (the repo name). JitPack publishes multi-module Gradle projects under one root coord; the jar contents are the api module.

Caution

The API depends on Adventure (net.kyori.adventure.text.*). Paper bundles Adventure, so on Paper the dependency is satisfied automatically. On plain Spigot you’ll need to shade or include Adventure yourself.

Declare the dependency in plugin.yml (Path 2 only)

Path 2 plugin-as-addons declare AbstractMenus as a hard dependency so Bukkit guarantees ordering — your onEnable runs after AbstractMenus is up.

plugin.yml

name: MyAddon
version: 1.0.0
depend:
  - AbstractMenus

Use softdepend: if your plugin should still load when AbstractMenus is missing — then guard API calls with Bukkit.getPluginManager().getPlugin("AbstractMenus") != null.

Path 1 addons don’t have a plugin.yml. They use addon.conf instead, with a pluginDependencies field. See the addons page.

Get the API instance

The entry point is AbstractMenusApi, looked up via the static get() method:

import ru.abstractmenus.api.AbstractMenusApi;

AbstractMenusApi api = AbstractMenusApi.get();

It returns null if AbstractMenus has not enabled yet. With depend: [AbstractMenus] declared, your onEnable will always see a non-null result.

For Path 1 addons, you don’t call get() at all — the API is passed as a parameter to the lifecycle methods:

public final class MyAddon implements MenuExtension {
    @Override
    public void onEnable(AbstractMenusApi api) {
        // api is already wired up
    }
}

What the API exposes

api.actions();         // TypeRegistry<Action>
api.rules();           // TypeRegistry<Rule>
api.activators();      // TypeRegistry<Activator>
api.itemProperties();  // TypeRegistry<ItemProperty>
api.catalogs();        // TypeRegistry<Catalog<?>>

api.providers();       // ProviderRegistry — economy, permissions, levels, placeholders, skins
api.serializers();     // shared HOCON NodeSerializers
api.variables();       // VariableManager — read/write player and global variables

api.openMenu(activator, ctx, player, menu);
api.getOpenedMenu(player);
api.loadMenus();

api.apiVersion();      // version string for diagnostics
api.getPlugin();       // raw Bukkit Plugin handle

Each registry, manager, and helper has its own page on this docs section.

Addon delivery Path 1 vs Path 2, MenuExtension lifecycle, addon.conf manifest.

Custom types Define and register your own actions, rules, item properties, activators, catalogs.

Provider handlers Plug in a custom economy / permissions / placeholder / skin / level backend.

Serializers HOCON deserialization for your own types.

Variables API Read and write player and global variables programmatically.

Utilities Color helpers, placeholder replacement, scheduling.

Migration 1.x → 2.0 Map old API calls (Types, Handlers, AbstractMenusProvider) to the new ones.

Optional: GitHub Packages instead of JitPack

If you must use GitHub Packages (e.g. CI policy):

1. Generate a Personal Access Token (classic) with the read:packages scope.

2. Put credentials in ~/.gradle/gradle.properties:

   ~/.gradle/gradle.properties

   gpr.user=your-github-username
   gpr.token=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

3. Add the repository and switch the coord to the native ru.abstractmenus:api:

   build.gradle

   repositories {
       maven {
           url = uri('https://maven.pkg.github.com/AbstractMenus/minecraft-plugin')
           credentials {
               username = providers.gradleProperty('gpr.user')
                       .orElse(providers.environmentVariable('GITHUB_ACTOR')).getOrNull()
               password = providers.gradleProperty('gpr.token')
                       .orElse(providers.environmentVariable('GITHUB_TOKEN')).getOrNull()
           }
       }
       // JitPack is still required for the api's transitive
       // com.github.AbstractMenus:hocon dep:
       maven { url 'https://jitpack.io' }
   }
   
   dependencies {
       compileOnly 'ru.abstractmenus:api:2.0.0-alpha.2'
   }