Schnellstart

Dieser Leitfaden hilft dir beim Einstieg in die Entwicklung von Pumpkin-Server-Plugins mit der Programmiersprache Zig.

Zig-Plugins für Pumpkin werden mithilfe der offiziellen Bindings pumpkin-api-zig als WebAssembly-Komponenten (Wasm) kompiliert.

---

Voraussetzungen

Bevor du Zig-Plugins für Pumpkin erstellst, stelle sicher, dass folgende Software installiert ist:

• Zig: Version 0.16.0 oder neuer.
• wasm-tools: In deinem PATH verfügbar (wird vom Build-Skript verwendet, um WIT-Metadaten einzubinden und die WebAssembly-Komponente zu erstellen).

---

1. Projekt einrichten

Erstelle ein neues Verzeichnis für dein Plugin-Projekt:

mkdir my-zig-plugin
cd my-zig-plugin

Füge pumpkin-api-zig als Abhängigkeit hinzu:

zig fetch --save git+https://github.com/Pumpkin-MC/pumpkin-api-zig

Erstelle die build.zig im Projektstammverzeichnis:

const std = @import("std");
const pumpkin_api = @import("pumpkin_api_zig");

pub fn build(b: *std.Build) void {
    _ = pumpkin_api.addPlugin(b, b.dependency("pumpkin_api_zig", .{}), .{
        .name = "my-zig-plugin",
        .root_source_file = b.path("src/main.zig"),
    });
}

---

2. Das Plugin schreiben

Erstelle ein src-Verzeichnis und lege deinen Code in src/main.zig ab:

const std = @import("std");
const pumpkin = @import("pumpkin");

pub const std_options: std.Options = .{ .logFn = pumpkin.logFn };

const MyPlugin = struct {
    pub const metadata: pumpkin.Metadata = .{
        .name = "my-zig-plugin",
        .version = "0.1.0",
        .authors = &.{"DeinName"},
        .description = "Ein Beispiel-Plugin in Zig.",
    };

    pub const events = .{
        .player_join_event = onJoin,
    };

    pub fn onLoad(_: pumpkin.Context) !void {
        std.log.info("Hallo von Zig!", .{});
    }

    fn onJoin(_: pumpkin.Server, ev: *pumpkin.EventData(.player_join_event)) void {
        std.log.info("{s} ist beigetreten", .{ev.player.getName()});
    }
};

comptime {
    pumpkin.register(MyPlugin);
}

Wichtige Elemente:

• std_options: Leitet das Standard-Zig-Logging (std.log) über pumpkin.logFn an das Logging-System von Pumpkin weiter.
• pub const metadata: Definiert Plugin-Metadaten (Name, Version, Autoren, Beschreibung), die von Pumpkin beim Laden der Komponente benötigt werden.
• pub const events: Registriert Event-Handler (wie .player_join_event).
• pub fn onLoad: Einstiegspunkt, der aufgerufen wird, wenn Pumpkin das Plugin initialisiert.
• pumpkin.register(MyPlugin): Generiert zur Compile-Zeit die erforderlichen WebAssembly-Komponenten-Exporte und Einstiegspunkte.

NOTE

Alles, was die API zurückgibt (einschließlich Handles), ist nur bis zur Rückkehr des aktuellen Callbacks gültig. Rufe keep() für ein Handle auf, um es zu behalten, und gib es anschließend mit deinit() frei.

---

3. Plugin kompilieren

Kompiliere dein Plugin zu einer WebAssembly-Komponente:

zig build

Dadurch wird zig-out/my-zig-plugin.wasm im Projektverzeichnis erzeugt.

---

4. Plugin ausführen

1. Kopiere die kompilierte .wasm-Datei in das plugins/-Verzeichnis deines Pumpkin-Servers:

   cp zig-out/my-zig-plugin.wasm /pfad/zu/pumpkin/plugins/

2. Starte oder starte den Pumpkin-Server neu:

   ./pumpkin

3. Prüfe die Server-Logs auf die Erfolgsmeldung:

   [INFO] Hallo von Zig!