123 lines
3.6 KiB
Markdown
123 lines
3.6 KiB
Markdown
# Schnellstart
|
|
|
|
Dieser Leitfaden hilft dir beim Einstieg in die Entwicklung von Pumpkin-Server-Plugins mit der Programmiersprache [Zig](https://ziglang.org/).
|
|
|
|
Zig-Plugins für Pumpkin werden mithilfe der offiziellen Bindings [`pumpkin-api-zig`](https://github.com/Pumpkin-MC/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](https://ziglang.org/download/)**: Version 0.16.0 oder neuer.
|
|
- **[`wasm-tools`](https://github.com/bytecodealliance/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:
|
|
|
|
```bash
|
|
mkdir my-zig-plugin
|
|
cd my-zig-plugin
|
|
```
|
|
|
|
Füge `pumpkin-api-zig` als Abhängigkeit hinzu:
|
|
|
|
```bash
|
|
zig fetch --save git+https://github.com/Pumpkin-MC/pumpkin-api-zig
|
|
```
|
|
|
|
Erstelle die `build.zig` im Projektstammverzeichnis:
|
|
|
|
```zig [build.zig]
|
|
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:
|
|
|
|
```zig [src/main.zig]
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
```bash
|
|
cp zig-out/my-zig-plugin.wasm /pfad/zu/pumpkin/plugins/
|
|
```
|
|
2. Starte oder starte den Pumpkin-Server neu:
|
|
```bash
|
|
./pumpkin
|
|
```
|
|
3. Prüfe die Server-Logs auf die Erfolgsmeldung:
|
|
```text
|
|
[INFO] Hallo von Zig!
|
|
```
|