Build plugins
without the pain.

Installation

First, you need to install the pumpkin-api-py library:

pip install pumpkin-api-py

Creating your first plugin

Create a file named main.py and add the following content:

from pumpkin_api import (
    Plugin, PluginMetadata, register_plugin, 
    server, event, command, text, context
)

class MyPlugin(Plugin):
    def metadata(self) -> PluginMetadata:
        return PluginMetadata(
            name="my-plugin",
            version="0.1.0",
            authors=["you"],
            description="An example plugin."
        )

    def on_load(self, ctx: context.Context) -> None:
        print("Python plugin loaded!")
        
        # Register an event handler
        self.register_event(ctx, event.EventType.PLAYER_JOIN_EVENT, self.on_player_join)

    def on_player_join(self, srv: server.Server, evt: event.PlayerJoinEventData) -> event.PlayerJoinEventData:
        print(f"Player {evt.player.get_name()} joined!")
        return evt

register_plugin(MyPlugin)

Building the plugin

Build your plugin into a WebAssembly component using the provided build tool:

pumpkin-api-build main -o my_plugin.wasm

This will generate a my_plugin.wasm file that you can place in the plugins folder of your Pumpkin server.

Installation

You will need the .NET SDK and the WASI workload to compile C# plugins for Pumpkin.

dotnet workload install wasi-experimental

Creating your first plugin

Create a new class library and add the following code:

using Pumpkin.API;

public class MyPlugin : IPlugin {
    public PluginMetadata GetMetadata() => new() {
        Name = "my-csharp-plugin",
        Version = "0.1.0",
        Authors = new[] { "you" },
        Description = "A simple C# plugin for Pumpkin"
    };

    public void OnLoad(IContext ctx) {
        Console.WriteLine("C# plugin loaded!");
    }
}

Building the plugin

Compile the plugin to WebAssembly using the WASI runtime identifier:

dotnet build -c Release /p:RuntimeIdentifier=wasi-wasm

This will generate a .wasm file in your output directory that can be loaded by Pumpkin.

Installation

You will need the wasi-sdk to compile C/C++ plugins for Pumpkin. Download the latest release from the wasi-sdk repository.

The complete code for this plugin can be found in the pumpkin-api-c repository.

Creating your first plugin

Create a file named main.c and add the following content:

#include "pumpkin_api.h"
#include <stdio.h>

// Define the plugin's metadata
pumpkin_metadata_t get_meta(void) {
    static const char* authors[] = {"you"};
    return (pumpkin_metadata_t) {
        .name = "my-c-plugin",
        .version = "0.1.0",
        .authors = authors,
        .authors_count = 1,
        .description = "A simple C plugin for Pumpkin",
        .dependencies_count = 0
    };
}

// Callback executed when the plugin is loaded
void on_load(plugin_own_context_t ctx) {
    printf("C plugin loaded!\n");
}

// Register the plugin with the API
REGISTER_PUMPKIN_PLUGIN(((pumpkin_plugin_t){
    .get_metadata = get_meta,
    .on_load = on_load
}))

Building the plugin

To compile this plugin into a WebAssembly component, use clang from the wasi-sdk:

/path/to/wasi-sdk/bin/clang -O3 \
 -Iinclude -Isrc/gen \
 src/gen/plugin.c src/pumpkin_api.c main.c \
 -o my_plugin.wasm \
 -mexec-model=reactor

This will generate a my_plugin.wasm file that can be loaded by Pumpkin.

Installation

You will need Go 1.23 or later and tinygo to compile Go plugins for Pumpkin.

brew tap tinygo-org/tools && brew install tinygo

Creating your first plugin

Create a file named main.go and add the following content:

package main

import (
    "fmt"
    "github.com/pumpkin-mc/pumpkin-api-go"
)

type MyPlugin struct{}

func (p *MyPlugin) Metadata() pumpkin.PluginMetadata {
    return pumpkin.PluginMetadata{
        Name:        "my-go-plugin",
        Version:     "0.1.0",
        Authors:     []string{"you"},
        Description: "A simple Go plugin for Pumpkin",
    }
}

func (p *MyPlugin) OnLoad(ctx pumpkin.Context) {
    fmt.Println("Go plugin loaded!")
}

func main() {
    pumpkin.RegisterPlugin(&MyPlugin{})
}

Building the plugin

Compile the plugin to WebAssembly using tinygo:

tinygo build -o my_plugin.wasm -target=wasi main.go

This will generate a my_plugin.wasm file that can be loaded by Pumpkin.

Installation

You will need a number of things installed.

• Git
• JDK 17+
• Rust (only default/host toolchain)
• wasm-tools
• make (e.g. GNU Make)

Unlike most of the other APIs, this one is actually a template instead. Clone it and rename.

git clone --recurse-submodules https://github.com/Pumpkin-MC/pumpkin-api-kt
mv pumpkin-api-kt my_kotlin_plugin
cd my_kotlin_plugin

Then change the rootProject.name in settings.gradle.kts, AND the PROJECT_NAME in Makefile. They must both match. Whatever you name the project, is going to be the filename of the Wasm produced.

Creating your first plugin

The template already has some code prepared. src/wasmWasiMain/kotlin/plugin/Plugin.kt contains:

package plugin;

import pumpkin.*

class PluginRootFunctionsExportsImpl {
    companion object : PluginRootFunctions.Exports {
        override fun initPlugin() {
            Logging.log(Logging.Level.INFO, "Init Kotlin plugin!")
        }

        override fun onLoad(context: Context.Context): Result<Unit> {
            Logging.log(Logging.Level.INFO, "Load Kotlin plugin!")
            return Result.success(Unit)
        }

        override fun onUnload(context: Context.Context): Result<Unit> {
            Logging.log(Logging.Level.INFO, "Unload Kotlin plugin!")
            return Result.success(Unit)
        }

        override fun handleCommand(
            commandId: UInt,
            sender: Command.CommandSender,
            server: Server.Server,
            args: Command.ConsumedArgs
        ): Result<Int> {
            TODO("Not yet implemented")
        }

        override fun handleEvent(eventId: UInt, server: Server.Server, event: Event.Event): Event.Event {
            TODO("Not yet implemented")
        }

        override fun handleTask(handlerId: UInt, server: Server.Server) {
            TODO("Not yet implemented")
        }
    }
}

class MetadataImpl {
    companion object : Metadata {
        override fun getMetadata(): Metadata.PluginMetadata {
            return Metadata.PluginMetadata(
                name = "Example Kotlin Plugin",
                version = "0.1.0",
                authors = listOf("You"),
                description = "An example plugin written in Kotlin",
                dependencies = listOf(),
                permissions = listOf()
            );
        }
    }
}

Building the plugin

Compile the plugin to WebAssembly by running the Makefile

make

This will take a while the first time as it builds some Rust dependencies from source.

Once it is done, my_kotlin_plugin.wasm (or whatever your Gradle project name is) will appear in build, ready to load into Pumpkin.