Create a plugin

On this page, you can find a basic Maven and Gradle configuration for your plugin.

Prerequirements

To develop a plugin of your wish you'll need:

Java Development Kit 21 or higher
Basic knowledge of programming in Java
A PowerNukkitX server
An IDE (Intellij IDEA, Eclipse, VS Code)

To develop a PowerNukkitX plugin, you need to configure a build tool (Maven or Gradle) to pull the server API and package your compiled plugin into a JAR file. Make sure your IDE project is targeting Java 21.

[!TIP] Instead of creating these files manually, you can clone or use the official PowerNukkitX Plugin Template to bootstrap a pre-configured project workspace.

Maven Setup

Open your project's pom.xml file and replace its contents with the following template. It configures the official PowerNukkitX repository, adds the server dependency, and sets up the maven-shade-plugin to package any external libraries you might use:

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.example</groupId>
    <artifactId>MyPlugin</artifactId>
    <version>1.0.0-SNAPSHOT</version>

    <properties>
        <maven.compiler.source>21</maven.compiler.source>
        <maven.compiler.target>21</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <repositories>
        <!-- Central Maven repository -->
        <repository>
            <id>central</id>
            <url>https://repo.maven.apache.org/maven2/</url>
        </repository>
        <!-- PowerNukkitX official repository -->
        <repository>
            <id>PowerNukkitX-releases</id>
            <name>PowerNukkitX Repository</name>
            <url>https://repo.powernukkitx.org/releases</url>
        </repository>
    </repositories>

    <dependencies>
        <!-- PowerNukkitX Server API (provided at runtime by the server)
             Use "3.0.0-SNAPSHOT" for the current release version, or
             "nightly-SNAPSHOT" for the latest development build (may contain API-breaking changes). -->
        <dependency>
            <groupId>org.powernukkitx</groupId>
            <artifactId>server</artifactId>
            <version>3.0.0-SNAPSHOT</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <!-- Compiler plugin targeting Java 21 -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.11.0</version>
                <configuration>
                    <source>21</source>
                    <target>21</target>
                </configuration>
            </plugin>
            <!-- Shade plugin to bundle non-provided dependencies into the output jar -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-shade-plugin</artifactId>
                <version>3.4.1</version>
                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>shade</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

To build your plugin, run the following command in your project directory:

mvn clean package

Your compiled JAR file will be located in the target/ directory.

Gradle Setup

If you prefer Gradle, create the following configuration files in your project root:

settings.gradle.kts:

rootProject.name = "MyPlugin"

build.gradle.kts: This setup utilizes the Kotlin DSL, pulls from the official PowerNukkitX repository, and configures the shadow plugin to package any libraries:

plugins {
    java
    id("com.github.johnrengelman.shadow") version "8.1.1"
}

group = "org.example"
version = "1.0.0-SNAPSHOT"

repositories {
    mavenCentral()
    // PowerNukkitX official repository
    maven {
        url = uri("https://repo.powernukkitx.org/releases")
    }
}

dependencies {
    // PowerNukkitX Server API (provided at runtime by the server)
    // Use "3.0.0-SNAPSHOT" for the current release version, or
    // "nightly-SNAPSHOT" for the latest development build (may contain API-breaking changes).
    compileOnly("org.powernukkitx:server:3.0.0-SNAPSHOT")
}

tasks.withType<JavaCompile> {
    options.encoding = "UTF-8"
    sourceCompatibility = "21"
    targetCompatibility = "21"
}

tasks {
    build {
        dependsOn(shadowJar)
    }
}

To build your plugin, run:

./gradlew clean build

Your compiled JAR file (packaged with any shaded libraries) will be located under build/libs/MyPlugin-1.0.0-SNAPSHOT-all.jar.

Creating the `plugin.yml` File

When using PowerNukkitX, you need a metadata file for your plugin. This file can be named powernukkitx.yml or plugin.yml. Create the file and paste the following content into it. Modify the values to fit your project:

name: ExamplePlugin
main: org.powernukkitx.exampleplugin.Main
# Remember: version and api must be strings, use quotes like "1.0.0"
version: "1.0.0"
api: "2.0.0"
load: POSTWORLD
author: PowerNukkitX Team
# author and authors are treated as one combined list
authors: ["Example", "Another"]
description: Example plugin from PNX documentation
website: https://docs.powernukkitx.org/

Writing Your Own Code

Now you can start writing your own code. Open the generated Main.java file in your project. Delete the existing Main class and replace it with the following code:

public class ExamplePlugin extends PluginBase {
    @Override
    public void onLoad() {
        this.getLogger().info(TextFormat.WHITE + "Example plugin loaded!");
    }

    @Override
    public void onEnable() {
        this.getLogger().info(TextFormat.DARK_GREEN + "Example plugin successfully enabled!");
    }

    @Override
    public void onDisable() {
        this.getLogger().info(TextFormat.DARK_RED + "Example plugin disabled!");
    }
}

Don’t forget the necessary imports:

import org.powernukkitx.plugin.PluginBase;
import org.powernukkitx.utils.TextFormat;

Congratulations! You can now run mvn package or ./gradlew assemble to build your plugin, place the generated JAR into your PNX server’s plugins folder, and restart the server.

Need Help?

If you need assistance, check out the Example Plugin or join our Discord server for support.

Prerequirements

Build System Configuration

Maven Setup

Gradle Setup

Creating the plugin.yml File

Writing Your Own Code

Need Help?

On this page

Creating the `plugin.yml` File