GH-118 Add multification-paper module with Paper platform support and examples

.github/workflows/gradle.yml

@@ -1,4 +1,4 @@
-name: Java CI with Gradle
+name: CI
 
 on:
   push:
@@ -8,29 +8,23 @@ on:
 
 jobs:
   build:
+    name: Build
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        java:
-          - 17
-      fail-fast: false
     steps:
       - name: Checkout
-        uses: actions/checkout@v4.3.1
-      - name: 'Set up JDK ${{ matrix.java }}'
-        uses: actions/setup-java@v4.8.0
-        with:
-          distribution: adopt
-          java-version: '${{ matrix.java }}'
-      - name: Cache Gradle
-        uses: actions/cache@v4.3.0
+        uses: actions/checkout@v5
+
+      - name: Set up JDK 21
+        uses: actions/setup-java@v5
         with:
-          path: ~/.gradle/caches
-          key: >-
-            ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*',
-            '**/gradle-wrapper.properties') }}
-          restore-keys: '${{ runner.os }}-gradle-'
-      - name: Grant execute permission for gradlew
+          distribution: 'temurin'
+          java-version: 21
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v5
+
+      - name: Make gradlew executable
         run: chmod +x gradlew
-      - name: Build the Jar
-        run: './gradlew clean test build'
+
+      - name: Build with Gradle
+        run: ./gradlew build

.github/workflows/publish-release.yml

@@ -1,25 +1,30 @@
 name: Publish Multification
+
 on:
   release:
-    branches: [ master ]
+    types: [published]
+
 jobs:
   publish:
+    name: Publish
     runs-on: ubuntu-latest
     environment: deployment
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
-      - name: Set up JDK
-        uses: actions/setup-java@v4
+      - name: Set up JDK 21
+        uses: actions/setup-java@v5
         with:
           distribution: 'temurin'
-          java-version: 17
-          cache: 'gradle'
+          java-version: 21
 
-      - name: Grant execute permission for gradlew
-        run: chmod +x gradlew
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v5
 
+      - name: Make gradlew executable
+        run: chmod +x gradlew
+
       - name: Publish with Gradle
         run: ./gradlew publish
         env:

README.md

@@ -1,7 +1,9 @@
 <div align="center">
-  
+
 ![Multification Banner](/assets/readme-banner.png)
+
 ### Multification
+
 Powerful library for sending custom notifications based on adventure.
 
 [![Patreon](https://raw.githubusercontent.com/intergrav/devins-badges/v3/assets/cozy/donate/patreon-plural_vector.svg)](https://www.patreon.com/eternalcode)
@@ -15,7 +17,9 @@ Powerful library for sending custom notifications based on adventure.
 
 ## About
 
-Multification makes it simple to create customizable notifications and messages within large plugins that require handling a high volume of messages (while the setup may not be easy, **it’s worthwhile for extensive plugins**). It offers a range of features, including:
+Multification makes it simple to create customizable notifications and messages within large plugins that require
+handling a high volume of messages (while the setup may not be easy, **it’s worthwhile for extensive plugins**). It
+offers a range of features, including:
 
 - 💭 Chat messages
 - 📕 Title & Subtitle
@@ -28,23 +32,55 @@ Multification makes it simple to create customizable notifications and messages
 - 🛠️ Formatter support
 - 🌎 Flexible messages providing (easy to implement i18n)
 - 📦 Configuration support (CDN, Okaeri Configs)
-- Cross-platform support (currently we support Bukkit, but it's easy to add support for other adventure-based platforms)
+- 🚀 Cross-platform support (Bukkit, Paper)
 
 Messages can be sent to any audience, such as players or the console.
 
+## Supported Platforms
+
+| Platform          | Module                 | Java Version | Adventure API         | Status                 |
+|-------------------|------------------------|--------------|-----------------------|------------------------|
+| **Paper**         | `multification-paper`  | Java 21      | Native (built-in)     | ✅ Recommended          |
+| **Bukkit/Spigot** | `multification-bukkit` | Java 8+      | External adapter      | ✅ Supported            |
+| **Velocity**      | `multification-velocity` | Java 21+     | Native                | ❌ Soon                 |
+| **Core**          | `multification-core`   | Java 8+      | Custom implementation | ✅ For custom platforms |
+
+> **💡 Recommendation:** Use `multification-paper` for Paper servers (1.19.4+) to leverage native Adventure API without
+> external dependencies.
+
 ## Getting Started
 
-To use the library, you need to add the following repository and dependency to your `build.gradle` file:
+### For Paper Servers (Recommended)
+
+Add the following repository and dependency to your `build.gradle.kts`:
 
 ```kts
-maven("https://repo.eternalcode.pl/releases")
+repositories {
+    maven("https://repo.eternalcode.pl/releases")
+    maven("https://repo.papermc.io/repository/maven-public/")
+}
+
+dependencies {
+    implementation("com.eternalcode:multification-paper:1.2.3")
+}
 ```
 
+### For Bukkit/Spigot Servers
+
 ```kts
-implementation("com.eternalcode:multification-bukkit:1.2.2")
+repositories {
+    maven("https://repo.eternalcode.pl/releases")
+}
+
+dependencies {
+    implementation("com.eternalcode:multification-bukkit:1.2.3")
+}
 ```
 
-> **Note:** If you want to use the library with other platforms, then you need to use the `multification-core` dependency.
+> **Note:** For custom platforms or other Adventure-based servers, use `multification-core` and implement your own
+> platform adapter.
+
+## Quick Example
 
 Then create a new instance of the `Multification` class and use it to send notifications:
 
@@ -55,7 +91,10 @@ public class YourMultification extends BukkitMultification<MessagesConfig> {
     private final AudienceProvider audienceProvider;
     private final MiniMessage miniMessage;
 
-    public YourMultification(MessagesConfig messagesConfig, AudienceProvider audienceProvider, MiniMessage miniMessage) {
+    public YourMultification(
+            MessagesConfig messagesConfig,
+            AudienceProvider audienceProvider,
+            MiniMessage miniMessage) {
         this.messagesConfig = messagesConfig;
         this.audienceProvider = audienceProvider;
         this.miniMessage = miniMessage;
@@ -73,15 +112,14 @@ public class YourMultification extends BukkitMultification<MessagesConfig> {
 
     @Override
     protected @NotNull AudienceConverter<CommandSender> audienceConverter() {
-        return  commandSender -> {
+        return commandSender -> {
             if (commandSender instanceof Player player) {
                 return this.audienceProvider.player(player.getUniqueId());
             }
 
             return this.audienceProvider.console();
         };
     }
-
 }
 ```
 
@@ -100,28 +138,32 @@ After that, you can use the `multification` instance to send notifications:
 
 ```java
 multification.create()
-    .player(player.getUniqueId())
-    .notice(messages -> messages.yourMessage)
-    .send();
+  .player(player.getUniqueId())
+  .notice(messages ->messages.yourMessage)
+  .send();
 ```
 
 ## Configuration Support
 
 Multification currently supports two configuration libraries:
+
 - [CDN](https://github.com/dzikoysk/cdn) _Simple and fast property-based configuration library for JVM apps_
-- [Okaeri Configs](https://github.com/OkaeriPoland/okaeri-configs) _Simple Java/POJO config library written with love and Lombok_
+- [Okaeri Configs](https://github.com/OkaeriPoland/okaeri-configs) _Simple Java/POJO config library written with love
+  and Lombok_
 
 To use the Multification library with one of the configuration libraries, you need to:
 
 ### [CDN](https://github.com/dzikoysk/cdn)
 
 #### (CDN) 1. Add dependency to your `build.gradle` file:
+
 ```gradle
 implementation("com.eternalcode:multification-cdn:1.1.4")
 implementation("net.dzikoysk:cdn:1.14.5")
 ```
 
 #### (CDN) 2. Create configuration class:
+
 ```java
 public class MessagesConfig {
     @Description("# My first message")
@@ -130,11 +172,12 @@ public class MessagesConfig {
 ```
 
 #### (CDN) 3. Create a new instance of the `Cdn` with the `MultificationNoticeCdnComposer`:
+
 ```java
 Cdn cdn = CdnFactory.createYamlLike()
-    .getSettings()
-    .withComposer(Notice.class, new MultificationNoticeCdnComposer(multification.getNoticeRegistry()))
-    .build();
+      .getSettings()
+      .withComposer(Notice.class, new MultificationNoticeCdnComposer(multification.getNoticeRegistry()))
+      .build();
 ```
 
 #### (CDN) 4. Load the configuration:
@@ -145,14 +188,12 @@ To load and create the config file, use the following code in the init method su
 MessagesConfig messages = new MessagesConfig();
 Resource resource = Source.of(this.dataFolder, "messages.yml");
 
-cdn.load(resource, messages)
-    .orThrow(cause -> cause);
-
-cdn.render(config, resource)
-    .orThrow(cause -> cause);
+cdn.load(resource, messages).orThrow(cause ->cause);
+cdn.render(config, resource).orThrow(cause ->cause);
 ```
 
-Checkout example with CDN! [example plugin](https://github.com/EternalCodeTeam/multification/tree/master/examples/bukkit).
+Checkout example with
+CDN! [example plugin](https://github.com/EternalCodeTeam/multification/tree/master/examples/bukkit).
 
 ### [Okaeri Configs](https://github.com/OkaeriPoland/okaeri-configs)
 
@@ -163,11 +204,13 @@ implementation("com.eternalcode:multification-okaeri:1.1.4")
 ```
 
 Probably also you will need to add additional dependencies for your platform, e.g. :
+
 ```gradle
 implementation("eu.okaeri:okaeri-configs-serdes-commons:5.0.5")
 implementation("eu.okaeri:okaeri-configs-serdes-bukkit:5.0.5")
 implementation("eu.okaeri:okaeri-configs-yaml-bukkit:5.0.5")
 ```
+
 See [Okaeri Configs](https://github.com/OkaeriPoland/okaeri-configs) for more information.
 
 #### (Okaeri) 2. Create configuration class:
@@ -183,11 +226,25 @@ public class MessagesConfig extends OkaeriConfig {
 
 ```java
 MessagesConfig config = (MessagesConfig) ConfigManager.create(MessagesConfig.class)
-    .withConfigurer(new MultificationSerdesPack(multification.getNoticeRegistry()))
-    .withConfigurer(new SerdesCommons(), new YamlBukkitConfigurer(), new SerdesBukkit()) // specify configurers for your platform
-    .withBindFile(new File(dataFolder, "messages.yml"))
-    .withRemoveOrphans(true) // automatic removal of undeclared keys
-    .saveDefaults() // save file if does not exists
-    .load(true);
+        .withConfigurer(new MultificationSerdesPack(multification.getNoticeRegistry()))
+        .withConfigurer(new SerdesCommons(), new YamlBukkitConfigurer(), new SerdesBukkit()) // specify configurers for your platform
+        .withBindFile(new File(dataFolder, "messages.yml"))
+        .withRemoveOrphans(true) // automatic removal of undeclared keys
+        .saveDefaults() // save file if does not exists
+        .load(true);
 ```
 
+## 📄 License
+
+This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
+
+## 🔗 Links
+
+- [GitHub Repository](https://github.com/EternalCodeTeam/multification)
+- [Discord Community](https://discord.gg/FQ7jmGBd6c)
+- [EternalCode Website](https://eternalcode.pl/)
+- [Issue Tracker](https://github.com/EternalCodeTeam/multification/issues)
+
+---
+
+Made with ❤️ by [EternalCodeTeam](https://github.com/EternalCodeTeam)

buildSrc/src/main/kotlin/multification-repositories.gradle.kts

@@ -5,7 +5,7 @@ plugins {
 repositories {
     mavenCentral()
 
-    maven("https://papermc.io/repo/repository/maven-public/") // paper, adventure, velocity
+    maven("https://repo.papermc.io/repository/maven-public/") // paper, adventure, velocity
     maven("https://hub.spigotmc.org/nexus/content/repositories/snapshots/") // spigot
     maven("https://repo.panda-lang.org/releases/") // expressible
     maven("https://repo.stellardrift.ca/repository/snapshots/")

examples/paper/build.gradle.kts

@@ -0,0 +1,60 @@
+plugins {
+    id("java")
+    id("com.gradleup.shadow") version "9.0.0-beta4"
+    id("net.minecrell.plugin-yml.paper") version "0.6.0"
+    id("xyz.jpenilla.run-paper") version "2.3.1"
+}
+
+version = "1.0.0-SNAPSHOT"
+
+java {
+    sourceCompatibility = JavaVersion.VERSION_21
+    targetCompatibility = JavaVersion.VERSION_21
+}
+
+repositories {
+    mavenCentral()
+    maven("https://repo.papermc.io/repository/maven-public/")
+    maven("https://repo.panda-lang.org/releases/")
+}
+
+dependencies {
+    compileOnly("io.papermc.paper:paper-api:1.21.4-R0.1-SNAPSHOT")
+
+    implementation("dev.rollczi:litecommands-bukkit:3.4.1")
+    // implementation("com.eternalcode:multification-paper:1.2.3") // <-- uncomment in your project
+    // implementation("com.eternalcode:multification-cdn:1.2.3") // <-- uncomment in your project
+
+    implementation(project(":multification-paper")) // don't use this line in your build.gradle
+    implementation(project(":multification-cdn")) // don't use this line in your build.gradle
+}
+
+val pluginName = "ExamplePaperPlugin"
+val packageName = "com.eternalcode.example.paper"
+
+paper {
+    main = "$packageName.$pluginName"
+    apiVersion = "1.21"
+    author = "EternalCode"
+    name = pluginName
+    version = "${project.version}"
+}
+
+tasks.shadowJar {
+    archiveFileName.set("$pluginName v${project.version}.jar")
+
+    listOf(
+        "dev.rollczi.litecommands",
+        "panda.std",
+        "panda.utilities",
+    ).forEach { relocate(it, "$packageName.libs.$it") }
+}
+
+sourceSets.test {
+    java.setSrcDirs(emptyList<String>())
+    resources.setSrcDirs(emptyList<String>())
+}
+
+tasks.runServer {
+    minecraftVersion("1.21.11")
+}