Rework API

.github/workflows/build.yml

@@ -38,8 +38,8 @@ jobs:
         with:
           gradle-home-cache-cleanup: true
 
-      - name: Build + tests
-        run: ./gradlew --no-daemon build shadowJar
+      - name: Build + tests (all modules) + shadowJar
+        run: ./gradlew --no-daemon build :plugin:shadowJar
 
       - name: Publish test report
         if: always()
@@ -49,14 +49,33 @@ jobs:
           fail_on_failure: true
           require_tests: false
 
-      - name: Resolve JAR path
-        id: jar
-        run: echo "path=$(ls build/libs/AbstractMenus-*.jar | head -n1)" >> "$GITHUB_OUTPUT"
+      - name: Resolve plugin JAR path
+        id: plugin_jar
+        # Skip the dev-only -thin jar; only the shaded fat jar ships.
+        run: echo "path=$(ls plugin/build/libs/AbstractMenus-*.jar | grep -v -- '-thin\.jar$' | head -n1)" >> "$GITHUB_OUTPUT"
 
-      - name: Upload shaded JAR
+      - name: Resolve API JAR paths
+        id: api_jars
+        run: |
+          echo "binary=$(ls api/build/libs/AbstractMenus-api-*.jar | grep -v 'sources\|javadoc' | head -n1)" >> "$GITHUB_OUTPUT"
+          echo "sources=$(ls api/build/libs/AbstractMenus-api-*-sources.jar | head -n1)" >> "$GITHUB_OUTPUT"
+          echo "javadoc=$(ls api/build/libs/AbstractMenus-api-*-javadoc.jar | head -n1)" >> "$GITHUB_OUTPUT"
+
+      - name: Upload plugin shadow JAR
         uses: actions/upload-artifact@v4
         with:
           name: AbstractMenus-jar
-          path: ${{ steps.jar.outputs.path }}
+          path: ${{ steps.plugin_jar.outputs.path }}
+          if-no-files-found: error
+          retention-days: 14
+
+      - name: Upload api artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: AbstractMenus-api
+          path: |
+            ${{ steps.api_jars.outputs.binary }}
+            ${{ steps.api_jars.outputs.sources }}
+            ${{ steps.api_jars.outputs.javadoc }}
           if-no-files-found: error
           retention-days: 14

.github/workflows/publish-api.yml

@@ -0,0 +1,40 @@
+name: Publish API to GitHub Packages
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag to re-publish'
+        required: true
+        type: string
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  publish:
+    name: Publish :api to GH Packages
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout (release tag)
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.release.tag_name || inputs.tag }}
+
+      - name: Set up JDK 21
+        uses: actions/setup-java@v4
+        with:
+          java-version: '21'
+          distribution: 'temurin'
+
+      - name: Set up Gradle
+        uses: gradle/actions/setup-gradle@v4
+
+      - name: Publish :api
+        run: ./gradlew --no-daemon :api:publish
+        env:
+          GITHUB_ACTOR: ${{ github.actor }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release.yml

@@ -6,7 +6,7 @@ on:
   workflow_dispatch:
     inputs:
       tag:
-        description: 'Existing release tag to attach a rebuilt JAR to'
+        description: 'Existing release tag to attach rebuilt JARs to'
         required: true
         type: string
 
@@ -15,7 +15,7 @@ permissions:
 
 jobs:
   attach-jar:
-    name: Build + attach JAR to release
+    name: Build + attach JARs to release
     runs-on: ubuntu-latest
     steps:
       - name: Checkout (release tag)
@@ -36,30 +36,39 @@ jobs:
       - name: Verify tag matches project version
         run: |
           TAG="${{ github.event.release.tag_name || inputs.tag }}"
-          # Strip a leading 'v' if present (v1.18.0 → 1.18.0)
           TAG_VERSION="${TAG#v}"
-          GRADLE_VERSION=$(grep -E "^version\s+['\"]" build.gradle | sed -E "s/.*['\"]([^'\"]+)['\"].*/\1/")
-          echo "release tag:      $TAG"
-          echo "tag version:      $TAG_VERSION"
-          echo "gradle version:   $GRADLE_VERSION"
+          GRADLE_VERSION=$(grep -E "^\s*version\s*=?\s*['\"]" build.gradle | head -n1 | sed -E "s/.*['\"]([^'\"]+)['\"].*/\1/")
+          echo "release tag:     $TAG"
+          echo "tag version:     $TAG_VERSION"
+          echo "gradle version:  $GRADLE_VERSION"
           if [ "$TAG_VERSION" != "$GRADLE_VERSION" ]; then
-            echo "::error::Release tag version ($TAG_VERSION) does not match build.gradle version ($GRADLE_VERSION). Bump build.gradle before tagging, or retag."
+            echo "::error::Release tag version ($TAG_VERSION) does not match root build.gradle version ($GRADLE_VERSION). Bump build.gradle before tagging, or retag."
             exit 1
           fi
 
-      - name: Build shaded JAR (skip tests — already run in Build workflow on the tagged commit)
-        run: ./gradlew --no-daemon shadowJar
+      - name: Build shadow plugin + api artifacts (skip tests — already run on the tagged commit by build.yml)
+        run: ./gradlew --no-daemon :plugin:shadowJar :api:build
 
-      - name: Resolve JAR path
-        id: jar
+      - name: Resolve artifact paths
+        id: paths
         run: |
-          JAR=$(ls build/libs/AbstractMenus-*.jar | head -n1)
-          echo "path=$JAR"       >> "$GITHUB_OUTPUT"
-          echo "name=$(basename "$JAR")" >> "$GITHUB_OUTPUT"
+          # Skip the dev-only -thin jar; only the shaded fat jar ships.
+          PLUGIN=$(ls plugin/build/libs/AbstractMenus-*.jar | grep -v -- '-thin\.jar$' | head -n1)
+          API_BIN=$(ls api/build/libs/AbstractMenus-api-*.jar | grep -v 'sources\|javadoc' | head -n1)
+          API_SRC=$(ls api/build/libs/AbstractMenus-api-*-sources.jar | head -n1)
+          API_DOC=$(ls api/build/libs/AbstractMenus-api-*-javadoc.jar | head -n1)
+          echo "plugin=$PLUGIN"  >> "$GITHUB_OUTPUT"
+          echo "api_bin=$API_BIN" >> "$GITHUB_OUTPUT"
+          echo "api_src=$API_SRC" >> "$GITHUB_OUTPUT"
+          echo "api_doc=$API_DOC" >> "$GITHUB_OUTPUT"
 
-      - name: Attach JAR to release
+      - name: Attach JARs to release
         uses: softprops/action-gh-release@v2
         with:
           tag_name: ${{ github.event.release.tag_name || inputs.tag }}
-          files: ${{ steps.jar.outputs.path }}
+          files: |
+            ${{ steps.paths.outputs.plugin }}
+            ${{ steps.paths.outputs.api_bin }}
+            ${{ steps.paths.outputs.api_src }}
+            ${{ steps.paths.outputs.api_doc }}
           fail_on_unmatched_files: true

.gitignore

@@ -1,4 +1,5 @@
 .gradle
 .idea
 build
-.DS_Strore
+.DS_Store
+logs

api/build.gradle

@@ -0,0 +1,77 @@
+plugins {
+    id 'java-library'
+    id 'maven-publish'
+}
+
+// Local file in api/build/libs/ is AbstractMenus-api-<ver>.jar so
+// it visually groups with AbstractMenus-<ver>.jar from :plugin and an
+// op who copies both off CI artifacts can tell at a glance both are AM.
+//
+// Maven publish artifactId stays 'api' (project.name) so the coord
+// 'ru.abstractmenus:api:<ver>' is unchanged for consumers - Gradle's
+// maven-publish renames files to <artifactId>-<version>.jar inside the
+// repository regardless of what archivesName is on the local jar task.
+base {
+    archivesName = 'AbstractMenus-api'
+}
+
+repositories {
+    // root already supplies papermc + jitpack + mavenCentral + mavenLocal
+}
+
+dependencies {
+    compileOnly 'io.papermc.paper:paper-api:1.21.11-R0.1-SNAPSHOT'
+    api 'com.github.AbstractMenus:hocon:1.0.6'
+
+    compileOnly 'org.projectlombok:lombok:1.18.44'
+    annotationProcessor 'org.projectlombok:lombok:1.18.44'
+
+    testImplementation 'org.junit.jupiter:junit-jupiter-api:5.14.3'
+    testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine:5.14.3'
+    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
+}
+
+java {
+    withSourcesJar()
+    withJavadocJar()
+}
+
+javadoc {
+    title = "AbstractMenus ${project.version} API"
+    options.addStringOption('Xdoclint:none', '-quiet')
+}
+
+publishing {
+    publications {
+        maven(MavenPublication) {
+            from components.java
+            // artifactId defaults to project.name == 'api'
+            // → Maven coord: ru.abstractmenus:api:<version>
+
+            pom {
+                name = 'AbstractMenus API'
+                description = 'Public API for the AbstractMenus Minecraft plugin (Paper/Folia).'
+                url = 'https://github.com/AbstractMenus/minecraft-plugin'
+                licenses {
+                    license {
+                        name = 'MIT License'
+                        url = 'https://github.com/AbstractMenus/minecraft-plugin/blob/master/LICENSE'
+                    }
+                }
+                scm {
+                    url = 'https://github.com/AbstractMenus/minecraft-plugin'
+                }
+            }
+        }
+    }
+    repositories {
+        maven {
+            name = 'GitHubPackages'
+            url  = uri('https://maven.pkg.github.com/AbstractMenus/minecraft-plugin')
+            credentials {
+                username = System.getenv('GITHUB_ACTOR')
+                password = System.getenv('GITHUB_TOKEN')
+            }
+        }
+    }
+}

api/src/main/java/ru/abstractmenus/api/AbstractMenusApi.java

@@ -0,0 +1,140 @@
+package ru.abstractmenus.api;
+
+import org.bukkit.Bukkit;
+import org.bukkit.entity.Player;
+import org.bukkit.plugin.Plugin;
+import ru.abstractmenus.api.inventory.ItemProperty;
+import ru.abstractmenus.api.inventory.Menu;
+import ru.abstractmenus.api.variables.VariableManager;
+import ru.abstractmenus.hocon.api.serialize.NodeSerializers;
+
+import java.util.Optional;
+
+/**
+ * Runtime entry point for AbstractMenus. Exposes the type registries, the
+ * shared HOCON {@link NodeSerializers}, menu lifecycle operations, and the
+ * variable manager.
+ *
+ * <p>Obtain the running instance via {@link #get()}:
+ *
+ * <pre>{@code
+ * AbstractMenusApi api = AbstractMenusApi.get();
+ * api.actions().register("myAction", MyAction.class, new MyAction.Serializer(), this);
+ * }</pre>
+ *
+ * <p>The implementation is registered against Bukkit's {@code ServicesManager}
+ * during the plugin's {@code onEnable()}. Do not call {@link #get()} before
+ * AbstractMenus has enabled &mdash; you will get {@code null}. For
+ * plugin-as-addon (Path 1) usage, call from your own {@code onEnable()} with
+ * {@code depend: [AbstractMenus]} in {@code plugin.yml} to guarantee ordering.
+ *
+ * @see MenuExtension
+ * @see TypeRegistry
+ */
+public interface AbstractMenusApi {
+
+    /**
+     * Look up the running API instance from Bukkit's ServicesManager.
+     *
+     * @return the running API, or {@code null} if AbstractMenus has not
+     *         enabled yet
+     */
+    static AbstractMenusApi get() {
+        return Bukkit.getServicesManager().load(AbstractMenusApi.class);
+    }
+
+    // ---- Registries -----------------------------------------------------
+
+    /** @return the action registry */
+    TypeRegistry<Action> actions();
+
+    /** @return the rule registry */
+    TypeRegistry<Rule> rules();
+
+    /** @return the activator registry */
+    TypeRegistry<Activator> activators();
+
+    /** @return the item-property registry */
+    TypeRegistry<ItemProperty> itemProperties();
+
+    /** @return the catalog registry */
+    TypeRegistry<Catalog<?>> catalogs();
+
+    /**
+     * Handler-provider registry (economy, permissions, levels, placeholders,
+     * skins). Replaces the old static {@code Handlers} facade.
+     *
+     * @return the provider registry
+     */
+    ProviderRegistry providers();
+
+    /**
+     * Shared HOCON serializer collection. Type registrations add to this
+     * automatically; consumers rarely need to access it directly.
+     *
+     * @return the shared serializer collection
+     */
+    NodeSerializers serializers();
+
+    // ---- Subsystems -----------------------------------------------------
+
+    /** @return the plugin's variable manager */
+    VariableManager variables();
+
+    /**
+     * The underlying Bukkit {@link Plugin} instance (the AbstractMenus
+     * plugin itself). Exposed for scheduler access and listener registration;
+     * prefer the high-level methods on this interface when possible.
+     *
+     * @return the plugin
+     */
+    Plugin getPlugin();
+
+    // ---- Menu lifecycle (migrated from AbstractMenusPlugin) -------------
+
+    /**
+     * Reload all menus from {@code plugins/AbstractMenus/menus/}. Called by
+     * {@code /am reload}.
+     */
+    void loadMenus();
+
+    /**
+     * Open a menu for a player with a triggering activator and context.
+     *
+     * @param activator the activator that triggered opening (may be
+     *                  {@code null} for programmatic opens)
+     * @param ctx       opening context (source entity/block/etc., may be
+     *                  {@code null})
+     * @param player    the viewer
+     * @param menu      the menu to open
+     */
+    void openMenu(Activator activator, Object ctx, Player player, Menu menu);
+
+    /**
+     * Open a menu for a player with no activator or context.
+     *
+     * @param player the viewer
+     * @param menu   the menu to open
+     */
+    void openMenu(Player player, Menu menu);
+
+    /**
+     * Get the menu currently open for {@code player}.
+     *
+     * @param player the viewer
+     * @return the open menu, or {@link Optional#empty()} if the player has no
+     *         AbstractMenus menu open
+     */
+    Optional<Menu> getOpenedMenu(Player player);
+
+    // ---- Meta -----------------------------------------------------------
+
+    /**
+     * API version string, taken from the plugin's {@code version}. Purely
+     * diagnostic &mdash; logged on startup and surfaced in
+     * {@code /am addons list}.
+     *
+     * @return the API version (e.g. {@code "2.0.0-alpha"})
+     */
+    String apiVersion();
+}