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.