Plugin Indexing Guide

This guide is written for plugin developers. If you want your project to appear on NukkitHub, follow the checklist below.

Quick Inclusion Checklist

To get your plugin included, make sure your repository satisfies all of the following:

1. Use a public GitHub repository
2. Do not archive the repository
3. Do not mark it as a template
4. Do not add the noindex topic
5. Put your manifest in the standard path
   • src/main/resources/plugin.yml
   • src/main/resources/nukkit.yml (supported by all Nukkit-family loaders)
   • or src/main/resources/powernukkitx.yml for PowerNukkitX-first modules
   • or use the PNX @PluginMeta annotation on your main class (see PowerNukkitX below)
6. Add the topic that matches your target runtime
7. Fill in your manifest and README.md

If you only do one extra thing beyond the manifest, add the correct topic. That makes discovery much more reliable.

Which Topic Should You Add?

Use the topic that best matches your plugin:

If your plugin supports both NukkitX and Nukkit-MOT, nukkit-plugin is acceptable.

How to add a topic: GitHub repository -> About -> gear icon -> Topics.

Fork note: If your plugin repository is a fork, adding the correct topic is especially important. Forks that publish no release of their own are treated as mirror copies and skipped.

What To Do For Each Runtime

NukkitX (nkx)

Recommended setup:

• Use src/main/resources/plugin.yml
• Add the nukkit-plugin topic
• Reference NukkitX-related runtime dependencies or strong repository markers such as:
  • cloudburstmc
  • repo.nukkitx.com

If your plugin uses generic cn.nukkit:* dependencies, it may be treated as shared compatibility for both NukkitX and Nukkit-MOT.

Nukkit-MOT (nkmot)

Recommended setup:

• Use src/main/resources/plugin.yml
• Add the nukkit-mot-plugin topic
• Reference Nukkit-MOT-related names in your build files, such as:
  • memoriesoftime
  • nukkit-mot

If your plugin supports both NukkitX and Nukkit-MOT, generic cn.nukkit:* dependencies are acceptable.

Important: MOTCI is not a repository submission channel. Your plugin still needs to be discoverable from GitHub.

PowerNukkitX (pnx)

Recommended setup — two supported styles:

Style A — hand-written manifest:

• Prefer src/main/resources/powernukkitx.yml
• Add powernukkitx-plugin or pnx-plugin
• Reference PowerNukkitX-related dependencies, such as:
  • org.powernukkitx (current package)
  • powernukkitx
  • repo.powernukkitx.org

Style B — @PluginMeta annotation (official PNX template style):

• Annotate your main class (the one extending PluginBase) with @PluginMeta
• Declare name, version, and api on the annotation; authors, description, website, depend, softDepend are also indexed
• No yml file is needed — the PNX annotation processor generates powernukkitx.yml at build time
• Add the powernukkitx-plugin or pnx-plugin topic so the repository is discovered reliably

Example:

@PluginMeta(
        name = "MyPlugin",
        version = "1.0.0",
        api = {"3.0.0"},
        authors = {"myname"},
        description = "A short description"
)
public class MyPlugin extends PluginBase {
}

Using powernukkitx.yml or @PluginMeta is the clearest way to make a PowerNukkitX module indexable.

Lumi (lumi)

Recommended setup:

• Use src/main/resources/plugin.yml
• Add the lumi-plugin topic
• Reference Lumi in Gradle or Maven, such as:
  • repo.lumi.su
  • repo.luminiadev.com as an auxiliary repository hint alongside shared Nukkit markers (legacy domain)
  • com.koshakmine:lumi
  • Maven coordinates containing com.koshakmine and lumi

Manifest Requirements

At least one supported manifest must exist in the standard path:

• src/main/resources/plugin.yml
• src/main/resources/nukkit.yml
• src/main/resources/powernukkitx.yml
• a @PluginMeta-annotated main class under src/main/java (PowerNukkitX only)

Example:

name: MyNukkitPlugin
version: 1.0.0
main: com.example.MyNukkitPlugin
api: ['1.0.0']
description: A short description of my plugin
website: https://example.com
depend: []
softdepend: []

Required Metadata

Authors are indexed from GitHub contributors. If no contributors are available, the repository owner is used.

Multi-Module Repositories

If your repository contains multiple plugin modules:

• each module should have its own manifest in src/main/resources/
• each module is indexed separately
• the generated IDs will look like owner/repo--module-suffix

Examples:

• Single-module repository: cooldev/myplugin-repo
• Multi-module repository: cooldev/myplugin-repo--modules-economy

Versions And Downloads

Your repository can be indexed without a GitHub Release, but a plugin with no installable version at all (no GitHub Release .jar and no ci- CI snapshot) is kept in a pending state: it stays tracked, yet does not appear in search results or the public API until its first version shows up.

Forks are expected to provide their own releases: a fork without any release of its own is treated as a mirror copy and is not indexed. Forks that adapt a plugin to another runtime (for example a Nukkit plugin reworked for PowerNukkitX) usually publish their own releases and are indexed normally.

If you want users to see downloadable versions on NukkitHub, publish releases this way:

1. Create a GitHub Release
2. Attach one or more .jar files
3. Use the release title and body as your version title and changelog

GitHub Releases are the primary source of plugin versions.

Additionally, if the repository has a job on motci.cn (the community Jenkins for Nukkit-MOT plugins), NukkitHub attaches the latest successful build as one extra snapshot version, named ci-{build} and flagged as a prerelease. The download links point to the Jenkins build artifacts.

In multi-module repositories, a CI artifact is only attached to the module whose plugin name matches the artifact filename.

Programmatic Access (Public API)

Indexed plugins are also available as machine-readable JSON through the NukkitHub public API, shaped after the Modrinth API:

• List plugins: https://plugins.nukkit-mot.com/api/v2/search.json (or the pre-filtered /api/v2/search/{loader}.json for a single runtime)
• Latest installable version of a plugin: /api/v2/project/{owner}/{name}/latest.json

Downloads come from GitHub Release .jar assets (see above) and, when the repository builds on motci.cn, the latest successful CI build as a prerelease snapshot version. See API.md for the full endpoint reference, response shapes, and compatibility notes for Modrinth-based tooling.

Categories

Add category topics to help users find your plugin:

README, Icon, And Gallery

To make your listing look complete after inclusion:

README

Your README.md becomes the main long description.

Recommended:

• explain what the plugin does
• show usage screenshots
• include installation steps
• keep links valid and public

Icon

To add a custom icon:

1. place logo.png or icon.png in .github/img/ or the repository root
2. use PNG format
3. recommended size: 256x256

If no icon is found, the repository owner's avatar is used.

Gallery Images

To add screenshots:

1. place PNG files in .github/img/
2. do not use logo.png or icon.png for screenshots
3. additional README images may also be picked up as gallery content

License

Add a standard license file if possible.

NukkitHub will try to read license information from:

1. GitHub's license detection
2. a LICENSE file in the repository root

If no open-source license is found, the project may appear as All Rights Reserved.

When A Plugin Will Not Be Indexed

Your plugin may be skipped or removed if any of the following is true:

To remove your plugin manually, add the noindex topic.

Tips To Get Indexed Faster

1. Add the correct runtime topic immediately
2. Put the manifest in src/main/resources/ from the start
3. Fill in name, version, main, and api
4. Keep README and repository metadata public
5. Publish a GitHub Release if you want downloadable versions visible
6. Add category topics, icon, and screenshots after the plugin is indexed

Example Repository Structure

my-nukkit-plugin/
├── .github/
│   └── img/
│       ├── logo.png
│       ├── gallery1.png
│       └── gallery2.png
├── src/
│   └── main/
│       ├── java/
│       │   └── com/example/
│       │       └── MyPlugin.java
│       └── resources/
│           └── plugin.yml
├── README.md
└── LICENSE

Troubleshooting

My plugin is not showing up

Check these items in order:

1. repository is public
2. repository is not archived
3. repository does not have the noindex topic
4. manifest exists in src/main/resources/, or your PNX plugin uses @PluginMeta
5. the runtime topic is set correctly
6. build files clearly reference the runtime you are targeting
7. it has at least one installable version (a GitHub Release with a .jar, or a ci- snapshot from motci) — otherwise it is indexed as pending and stays hidden until the first version appears
8. if it is a fork, it has a release of its own — forks without releases are treated as mirror copies
9. wait up to 1 hour for the next indexing cycle

My project is indexed but has no downloads

Make sure you created a GitHub Release and attached a .jar file. Without any installable version the project stays pending: tracked, but hidden from search and the API.

My runtime is detected incorrectly

Use the topic that matches your runtime and make your build files reference the matching core clearly.