Add Nexus deployment workflow, Maven publishing, and utilities (#3)

* Add Nexus deploy workflow and Maven publishing

Add a GitHub Actions workflow to deploy artifacts to Negative Games Nexus for release and snapshot branches. The workflow sets up JDK 21 and Gradle, injects Nexus credentials into ~/.gradle/gradle.properties from secrets, adjusts module apiVersion for release/snapshot branches, and runs ./gradlew publish with an isRelease flag.

Update root build.gradle.kts to apply maven-publish and configure a nexus repository that selects snapshots or releases based on the isRelease property and reads credentials from gradle.properties. Add maven-publish and shadow publishing configuration to common and paper modules: set module ids, domain, apiVersion, Java 21 toolchain, disable the plain jar, configure shadowJar as the published artifact, and include POM metadata (license, developer, url).

* Update deploy workflow for Kotlin DSL builds

Switch sed targets from build.gradle to build.gradle.kts and update the regexes to match Kotlin DSL variable declarations (var apiVersion = "...") for both release and snapshot branches. This ensures version bump/removal works for build.gradle.kts files. Also add a missing newline at end of file.

* Remove disabling of tasks.jar

Delete the tasks.jar { enabled = false } block from common/build.gradle.kts so the default jar task is no longer disabled. This restores normal jar packaging behavior while keeping the shadowJar configuration (archiveBaseName and archiveVersion) intact.

* Add README and PaperCommand; update registry (#2)

Add project README documenting modules, usage, and APIs. Introduce PaperCommand interface (CloudCommand specialized for CommandSourceStack) and update PaperCommandRegistry to discover/register PaperCommand beans (remove unused CloudCommand import). This aligns command discovery with the Paper-specific command type and adds library documentation.

* Add IntList utility to parse integer ranges

Introduce IntList with a static parse(List<String>) method that converts strings into a List<Integer>. Supports single integers and inclusive ranges (e.g., "5-10"); input segments are trimmed before parsing. Useful for parsing config or input lists; invalid numeric input will throw NumberFormatException.

* Add JsonUtil utility for Gson file I/O

Introduce JsonUtil, a final utility class (Slf4j) providing Gson-based JSON file operations. Adds methods to load/save objects: loadFromFile, loadTypeFromFile, loadFromDirectory, saveToFile and saveTypeToFile. Uses UTF-8 encoding, Optional/Collection return types, basic file existence checks and error logging, and prevents instantiation.

* Add Cooldowns component for player cooldowns

Introduce a Cooldowns Spring component and Bukkit Listener to manage per-player, per-key cooldowns. Uses a Guava Table backed by concurrent maps to store expiry timestamps (epoch millis), provides addCooldown overloads (millis and Duration) and an isOnCooldown check. Clears a player's cooldowns on PlayerQuitEvent to prevent memory leaks.

* Add OptionalBool utility for boolean ops

Introduce OptionalBool to wrap boolean values and provide Optional-like, functional-style operations. The class uses singleton instances for true/false, offers isTrue/isFalse checks, conditional executors (ifTrue, ifFalse, ifTrueOrElse) and mapping utilities (mapIfTrue, mapIfFalse, mapIfTrueOrElse) that return Optional or computed values. Also overrides equals, hashCode, and toString. Placed in games.negative.engine.util for use across the codebase.

* Add Reloadable and reload impl to PaperPlugin

Introduce a new Reloadable interface with a single reload() method and implement plugin reload handling in PaperPlugin. PaperPlugin now invokes Reloadable beans via invokeBeans, calling their reload methods and logging any failures using SLF4J (@slf4j). Adds the new common interface file and updates imports in the Paper module.

* Register Spring Listeners on enable; log commands

PaperPlugin: onEnable now invokes Spring beans of type org.bukkit.event.Listener and registers them with the server PluginManager, logging any registration failures. Added the Listener import. PaperCommandRegistry: added an info log "Registering commands" at the start of onEnable to surface command registration in logs.

* Bump API version to 1.1.0

Update apiVersion from 1.0.0 to 1.1.0 in common/build.gradle.kts and paper/build.gradle.kts to reflect the API minor release.

Author: ericlmao

README.md

@@ -0,0 +1,245 @@
+# plugin-engine
+
+A Java 21 library for building Minecraft Paper plugins with reusable building blocks for commands, scheduling, GUIs, messaging, configuration, and utility helpers.
+
+## What this library provides
+
+`plugin-engine` is split into two modules:
+
+| Module | Artifact | Purpose |
+| --- | --- | --- |
+| common | `games.negative.engine:plugin-engine-common` | Platform-agnostic APIs and helpers (configuration, messages, command abstractions, utilities). |
+| paper | `games.negative.engine:plugin-engine-paper` | Paper-specific implementations (plugin base class, schedulers, command registration, GUI framework, item builder, jobs). |
+
+## Compatibility
+
+- Java 21
+- Paper API `1.21.8-R0.1-SNAPSHOT` (for the `paper` module)
+
+## Installation
+
+Add the Negative Games Maven repository:
+
+### Gradle (Kotlin DSL)
+
+```kotlin
+repositories {
+    maven("https://repo.negative.games/repository/maven-releases/")
+    maven("https://repo.negative.games/repository/maven-snapshots/")
+}
+```
+
+Then add dependencies:
+
+```kotlin
+dependencies {
+    implementation("games.negative.engine:plugin-engine-paper:1.0.0")
+    // or: implementation("games.negative.engine:plugin-engine-common:1.0.0")
+}
+```
+
+### Maven
+
+```xml
+<repositories>
+    <repository>
+        <id>negative-games-releases</id>
+        <url>https://repo.negative.games/repository/maven-releases/</url>
+    </repository>
+    <repository>
+        <id>negative-games-snapshots</id>
+        <url>https://repo.negative.games/repository/maven-snapshots/</url>
+    </repository>
+</repositories>
+```
+
+```xml
+<dependencies>
+    <dependency>
+        <groupId>games.negative.engine</groupId>
+        <artifactId>plugin-engine-paper</artifactId>
+        <version>1.0.0</version>
+    </dependency>
+</dependencies>
+```
+
+Use `-SNAPSHOT` versions when consuming snapshot builds.
+
+## Quick start (Paper plugins)
+
+### 1) Extend `PaperPlugin`
+
+```java
+package com.example;
+
+import games.negative.engine.paper.PaperPlugin;
+
+public final class ExamplePlugin extends PaperPlugin {
+}
+```
+
+`PaperPlugin` initializes scheduler and MiniMessage utilities for you and exposes the shared `Plugin` contract (`directory()`, `fetchBeans(...)`).
+
+### 2) Optional: custom library loader
+
+If you need extra runtime libraries, extend `PaperPluginLoader`:
+
+```java
+package com.example;
+
+import games.negative.engine.paper.loader.PaperPluginLoader;
+import org.eclipse.aether.graph.Dependency;
+import io.papermc.paper.plugin.loader.library.impl.MavenLibraryResolver;
+
+public final class ExamplePluginLoader extends PaperPluginLoader {
+    @Override
+    public void addLibraries(MavenLibraryResolver resolver) {
+        Dependency dep = dependency("com.example:example-lib:1.2.3");
+        resolver.addDependency(dep);
+    }
+}
+```
+
+## Commands
+
+`paper` includes `PaperCommandRegistry`, which auto-discovers Spring beans implementing `CloudCommand` and `CloudArgument`.
+
+```java
+package com.example.command;
+
+import games.negative.engine.command.CloudCommand;
+import games.negative.moss.spring.SpringComponent;
+import io.papermc.paper.command.brigadier.CommandSourceStack;
+import org.incendo.cloud.CommandManager;
+import org.incendo.cloud.annotations.Command;
+import org.incendo.cloud.annotations.CommandDescription;
+
+@SpringComponent
+public final class ExampleCommand implements PaperCommand {
+
+    @Command("example")
+    @CommandDescription("Example command")
+    public void example(CommandSourceStack source) {
+        
+    }
+}
+```
+
+## Scheduling and jobs
+
+Use the static `Scheduler` accessors:
+
+```java
+Scheduler.sync().run(task -> {
+    // Main-thread/global region work
+});
+
+Scheduler.async().run(task -> {
+    // Async work
+});
+
+Scheduler.entity(player).execute(() -> {
+    // Entity-thread safe work
+}, 1L);
+```
+
+For recurring background logic, create beans implementing `SyncJob` or `AsyncJob`; `JobScheduler` auto-registers them on enable:
+
+```java
+@SpringComponent
+public final class AnnounceJob implements SyncJob {
+    @Override
+    public Duration interval() {
+        return Duration.ofSeconds(30);
+    }
+
+    @Override
+    public void tick(ScheduledTask task) {
+        // Repeating logic
+    }
+}
+```
+
+## GUI framework
+
+Use `ChestMenu`, `PaginatedMenu`, or `HopperMenu` with `Button`:
+
+```java
+public final class ExampleMenu extends ChestMenu {
+    public ExampleMenu(Player player) {
+        super(player, "<green>Example", 3);
+
+        addButton(13, Button.builder()
+                .item(viewer -> ItemBuilder.of(Material.EMERALD)
+                        .name("<green>Click me")
+                        .build())
+                .action((button, viewer, event) -> viewer.sendMessage(Component.text("Clicked")))
+                .build());
+    }
+}
+```
+
+Menus are cached per-player and handled by `PlayerInventoryController`.
+
+## Messages and placeholders
+
+`Message` and `MiniMessageUtil` support MiniMessage formatting plus PlaceholderAPI integration (when present):
+
+```java
+Message.of("<gold>Hello, <name>!")
+        .send(player, Placeholder.parsed("name", player.getName()));
+```
+
+`PaperLocalizationPlatform` provides PlaceholderAPI and relational placeholder parsing for Paper audiences.
+
+## Configuration
+
+Use `Configuration<T>` with ConfigLib-backed YAML storage:
+
+```java
+public final class ExampleConfig {
+    public String prefix = "<gray>[Example]</gray>";
+}
+
+Configuration<ExampleConfig> config = Configuration.config(
+        plugin.directory().resolve("config.yml").toFile(),
+        ExampleConfig.class
+);
+
+String prefix = config.get().prefix;
+```
+
+## Item building
+
+`ItemBuilder` simplifies `ItemStack` creation:
+
+```java
+ItemStack stack = ItemBuilder.of(Material.DIAMOND_SWORD)
+        .name("<aqua>Starter Sword")
+        .lore(List.of("<gray>Given on join"))
+        .unbreakable(true)
+        .glowing(true)
+        .build();
+```
+
+## Utilities in `common`
+
+- `TimeUtil`: parse/format durations (`1d2h30m`, `H:MM:SS`, etc.)
+- `NumberUtil`: decimal formatting, ordinals (`1st`, `2nd`), condensed numbers (`1.2M`)
+- `AABB` (paper): simple axis-aligned bounding box representation
+
+## Build and publish
+
+From repository root:
+
+```bash
+./gradlew clean build
+```
+
+Publishing (used by CI for `release` / `snapshot` branches):
+
+```bash
+./gradlew clean publish -PisRelease=true   # releases repo
+./gradlew clean publish -PisRelease=false  # snapshots repo
+```
+

common/build.gradle.kts

@@ -6,7 +6,7 @@ plugins {
 
 var id = "plugin-engine-common"
 var domain = "games.negative.engine"
-var apiVersion = "1.0.0"
+var apiVersion = "1.1.0"
 
 repositories {
     mavenCentral()

common/src/main/java/games/negative/engine/state/Reloadable.java

@@ -0,0 +1,7 @@
+package games.negative.engine.state;
+
+public interface Reloadable {
+
+    void reload();
+
+}

common/src/main/java/games/negative/engine/util/IntList.java

@@ -0,0 +1,34 @@
+package games.negative.engine.util;
+
+import java.util.ArrayList;
+import java.util.List;
+
+public class IntList {
+
+    /**
+     * Parses a list of strings into a list of integers.
+     * Strings can represent single integers or ranges (e.g., "5-10").
+     *
+     * @param strings The list of strings to parse.
+     * @return A list of integers.
+     */
+    public static List<Integer> parse(List<String> strings) {
+        List<Integer> list = new ArrayList<>();
+
+        for (String string : strings) {
+            if (string.contains("-")) {
+                String[] range = string.split("-", 2);
+                int start = Integer.parseInt(range[0].trim());
+                int end = Integer.parseInt(range[1].trim());
+
+                for (int i = start; i <= end; i++) {
+                    list.add(i);
+                }
+            } else {
+                list.add(Integer.parseInt(string.trim()));
+            }
+        }
+
+        return list;
+    }
+}