diff --git a/docs/.vitepress/de.ts b/docs/.vitepress/de.ts index 34bac52..223ca4b 100644 --- a/docs/.vitepress/de.ts +++ b/docs/.vitepress/de.ts @@ -368,6 +368,16 @@ export const de = defineConfig({ }, ], }, + { + text: "Zig", + collapsed: true, + items: [ + { + text: "Schnellstart", + link: "/de/plugin-dev/zig/quick-start", + }, + ], + }, ], }, { diff --git a/docs/.vitepress/en.ts b/docs/.vitepress/en.ts index 77271b8..5b41c01 100644 --- a/docs/.vitepress/en.ts +++ b/docs/.vitepress/en.ts @@ -369,6 +369,16 @@ export const en = defineConfig({ }, ], }, + { + text: "Zig", + collapsed: true, + items: [ + { + text: "Quick Start", + link: "/plugin-dev/zig/quick-start", + }, + ], + }, ], }, { diff --git a/docs/.vitepress/ja_jp.ts b/docs/.vitepress/ja_jp.ts index a15bbe4..454d94e 100644 --- a/docs/.vitepress/ja_jp.ts +++ b/docs/.vitepress/ja_jp.ts @@ -368,6 +368,16 @@ export const jaJP = defineConfig({ }, ], }, + { + text: "Zig", + collapsed: true, + items: [ + { + text: "クイックスタート", + link: "/ja_jp/plugin-dev/zig/quick-start", + }, + ], + }, ], }, { diff --git a/docs/.vitepress/nl.ts b/docs/.vitepress/nl.ts index 74ded7e..8f53c71 100644 --- a/docs/.vitepress/nl.ts +++ b/docs/.vitepress/nl.ts @@ -368,6 +368,16 @@ export const nl = defineConfig({ }, ], }, + { + text: "Zig", + collapsed: true, + items: [ + { + text: "Quick Start", + link: "/nl/plugin-dev/zig/quick-start", + }, + ], + }, ], }, { diff --git a/docs/.vitepress/pt.ts b/docs/.vitepress/pt.ts index 3dbf0e9..667a27a 100644 --- a/docs/.vitepress/pt.ts +++ b/docs/.vitepress/pt.ts @@ -368,6 +368,16 @@ export const pt = defineConfig({ }, ], }, + { + text: "Zig", + collapsed: true, + items: [ + { + text: "Início Rápido", + link: "/pt/plugin-dev/zig/quick-start", + }, + ], + }, ], }, { diff --git a/docs/.vitepress/tr_tr.ts b/docs/.vitepress/tr_tr.ts index 051fed7..8d91829 100644 --- a/docs/.vitepress/tr_tr.ts +++ b/docs/.vitepress/tr_tr.ts @@ -368,6 +368,16 @@ export const trTR = defineConfig({ }, ], }, + { + text: "Zig", + collapsed: true, + items: [ + { + text: "Hızlı Başlangıç", + link: "/tr_TR/plugin-dev/zig/quick-start", + }, + ], + }, ], }, { diff --git a/docs/.vitepress/zh_cn.ts b/docs/.vitepress/zh_cn.ts index 00ddfd3..6c837b3 100644 --- a/docs/.vitepress/zh_cn.ts +++ b/docs/.vitepress/zh_cn.ts @@ -368,6 +368,16 @@ export const zhCN = defineConfig({ }, ], }, + { + text: "Zig", + collapsed: true, + items: [ + { + text: "快速入门", + link: "/zh_cn/plugin-dev/zig/quick-start", + }, + ], + }, ], }, { diff --git a/docs/de/plugin-dev/introduction.md b/docs/de/plugin-dev/introduction.md index 15ecaf7..18839ac 100644 --- a/docs/de/plugin-dev/introduction.md +++ b/docs/de/plugin-dev/introduction.md @@ -8,7 +8,7 @@ Wenn du auf Probleme stößt, melde dich bitte auf unserem [Discord‑Server](ht Pumpkin‑Plugins integrieren sich sehr tief in die Server‑Software und ermöglichen dadurch viele Dinge, die auf anderer Serversoftware nicht möglich wären. -Die Pumpkin Plugin API orientiert sich in vielen Bereichen an der Spigot/Bukkit Plugin API. Wenn du damit bereits Erfahrung hast und Rust, Python, C#, Go oder C beherrscht, solltest du relativ einfach Plugins für Pumpkin schreiben können. :smile: +Die Pumpkin Plugin API orientiert sich in vielen Bereichen an der Spigot/Bukkit Plugin API. Wenn du damit bereits Erfahrung hast und Rust, Python, C#, Go, C, Kotlin, D oder Zig beherrscht, solltest du relativ einfach Plugins für Pumpkin schreiben können. :smile: * [Rust API](https://github.com/Pumpkin-MC/Pumpkin) * [Python API](https://github.com/Pumpkin-MC/pumpkin-api-py) @@ -17,3 +17,4 @@ Die Pumpkin Plugin API orientiert sich in vielen Bereichen an der Spigot/Bukkit * [C API](https://github.com/Pumpkin-MC/pumpkin-api-c) * [Kotlin API](https://github.com/Pumpkin-MC/pumpkin-api-kt) * [D API](https://github.com/Pumpkin-MC/pumpkin-api-d) +* [Zig API](https://github.com/Pumpkin-MC/pumpkin-api-zig) diff --git a/docs/de/plugin-dev/zig/quick-start.md b/docs/de/plugin-dev/zig/quick-start.md new file mode 100644 index 0000000..7cc9627 --- /dev/null +++ b/docs/de/plugin-dev/zig/quick-start.md @@ -0,0 +1,122 @@ +# 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! + ``` diff --git a/docs/en/plugin-dev/introduction.md b/docs/en/plugin-dev/introduction.md index dfa95d4..96f10bd 100644 --- a/docs/en/plugin-dev/introduction.md +++ b/docs/en/plugin-dev/introduction.md @@ -6,7 +6,7 @@ If you run into any issues please reach out on [our Discord server](https://disc ::: The Pumpkin Plugin API takes inspiration from the Spigot/Bukkit plugin API in many places, -so if you have previous experience with these and have experience with Rust, Python, C#, Go, C, Kotlin, or D development, +so if you have previous experience with these and have experience with Rust, Python, C#, Go, C, Kotlin, D, or Zig development, you should have a pretty easy time writing plugins for Pumpkin. :smile: * [Rust API](https://github.com/Pumpkin-MC/Pumpkin) @@ -16,3 +16,4 @@ you should have a pretty easy time writing plugins for Pumpkin. :smile: * [C API](https://github.com/Pumpkin-MC/pumpkin-api-c) * [Kotlin API](https://github.com/Pumpkin-MC/pumpkin-api-kt) * [D API](https://github.com/Pumpkin-MC/pumpkin-api-d) +* [Zig API](https://github.com/Pumpkin-MC/pumpkin-api-zig) diff --git a/docs/en/plugin-dev/zig/quick-start.md b/docs/en/plugin-dev/zig/quick-start.md new file mode 100644 index 0000000..deb34bd --- /dev/null +++ b/docs/en/plugin-dev/zig/quick-start.md @@ -0,0 +1,122 @@ +# Quick Start + +This guide will help you get started with writing Pumpkin server plugins using the [Zig programming language](https://ziglang.org/). + +Zig plugins for Pumpkin compile to WebAssembly (Wasm) components using the official [`pumpkin-api-zig`](https://github.com/Pumpkin-MC/pumpkin-api-zig) bindings. + +--- + +## Prerequisites + +Before building Zig plugins for Pumpkin, ensure you have the following installed: + +- **[Zig](https://ziglang.org/download/)**: Version 0.16.0 or later. +- **[`wasm-tools`](https://github.com/bytecodealliance/wasm-tools)**: Available in your `PATH` (used by the build script to embed WIT metadata and generate the WebAssembly component). + +--- + +## 1. Setting Up the Project + +Create a new directory for your plugin project: + +```bash +mkdir my-zig-plugin +cd my-zig-plugin +``` + +Fetch and add `pumpkin-api-zig` as a dependency: + +```bash +zig fetch --save git+https://github.com/Pumpkin-MC/pumpkin-api-zig +``` + +Create `build.zig` in the project root: + +```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. Writing the Plugin + +Create a `src` directory and add your plugin code in `src/main.zig`: + +```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 = &.{"You"}, + .description = "An example plugin in Zig.", + }; + + pub const events = .{ + .player_join_event = onJoin, + }; + + pub fn onLoad(_: pumpkin.Context) !void { + std.log.info("Hello from Zig!", .{}); + } + + fn onJoin(_: pumpkin.Server, ev: *pumpkin.EventData(.player_join_event)) void { + std.log.info("{s} joined", .{ev.player.getName()}); + } +}; + +comptime { + pumpkin.register(MyPlugin); +} +``` + +### Key Elements: +- **`std_options`**: Routes standard Zig logging (`std.log`) to Pumpkin's logger using `pumpkin.logFn`. +- **`pub const metadata`**: Defines plugin metadata (name, version, authors, description) required by Pumpkin when loading the component. +- **`pub const events`**: Defines event handlers registered by the plugin (such as `.player_join_event`). +- **`pub fn onLoad`**: Entry point invoked when Pumpkin initializes the plugin. +- **`pumpkin.register(MyPlugin)`**: Generates the necessary WebAssembly component exports and entry points at compile time. + +> [!NOTE] +> Everything the API returns (handles included) is only valid until the current callback returns. Call `keep()` on a handle to hold on to it, then release it with `deinit()` when you're done. + +--- + +## 3. Building the Plugin + +Compile your plugin into a WebAssembly component: + +```bash +zig build +``` + +This will produce `zig-out/my-zig-plugin.wasm` in your project root. + +--- + +## 4. Running Your Plugin + +1. Copy the compiled `.wasm` file to your server's `plugins/` directory: + ```bash + cp zig-out/my-zig-plugin.wasm /path/to/pumpkin/plugins/ + ``` +2. Start or restart Pumpkin: + ```bash + ./pumpkin + ``` +3. Check the server logs to verify your plugin loaded: + ```text + [INFO] Hello from Zig! + ``` diff --git a/docs/ja_jp/plugin-dev/introduction.md b/docs/ja_jp/plugin-dev/introduction.md index dfa95d4..96f10bd 100644 --- a/docs/ja_jp/plugin-dev/introduction.md +++ b/docs/ja_jp/plugin-dev/introduction.md @@ -6,7 +6,7 @@ If you run into any issues please reach out on [our Discord server](https://disc ::: The Pumpkin Plugin API takes inspiration from the Spigot/Bukkit plugin API in many places, -so if you have previous experience with these and have experience with Rust, Python, C#, Go, C, Kotlin, or D development, +so if you have previous experience with these and have experience with Rust, Python, C#, Go, C, Kotlin, D, or Zig development, you should have a pretty easy time writing plugins for Pumpkin. :smile: * [Rust API](https://github.com/Pumpkin-MC/Pumpkin) @@ -16,3 +16,4 @@ you should have a pretty easy time writing plugins for Pumpkin. :smile: * [C API](https://github.com/Pumpkin-MC/pumpkin-api-c) * [Kotlin API](https://github.com/Pumpkin-MC/pumpkin-api-kt) * [D API](https://github.com/Pumpkin-MC/pumpkin-api-d) +* [Zig API](https://github.com/Pumpkin-MC/pumpkin-api-zig) diff --git a/docs/ja_jp/plugin-dev/zig/quick-start.md b/docs/ja_jp/plugin-dev/zig/quick-start.md new file mode 100644 index 0000000..01abd84 --- /dev/null +++ b/docs/ja_jp/plugin-dev/zig/quick-start.md @@ -0,0 +1,122 @@ +# クイックスタート + +このガイドでは、[Zig言語](https://ziglang.org/)を使用してPumpkinサーバープラグインを作成する手順を説明します。 + +Pumpkin用のZig言語プラグインは、公式の[`pumpkin-api-zig`](https://github.com/Pumpkin-MC/pumpkin-api-zig)バインディングを使用してWebAssembly (Wasm) コンポーネントにコンパイルされます。 + +--- + +## 前提条件 + +開始する前に、以下のツールがインストールされていることを確認してください: + +- **[Zig](https://ziglang.org/download/)**: バージョン 0.16.0 以降。 +- **[`wasm-tools`](https://github.com/bytecodealliance/wasm-tools)**: `PATH` に設定されていること (ビルドスクリプトがWITメタデータを埋め込み、WebAssemblyコンポーネントを生成するために使用します)。 + +--- + +## 1. プロジェクトのセットアップ + +プラグインプロジェクト用の新しいディレクトリを作成します: + +```bash +mkdir my-zig-plugin +cd my-zig-plugin +``` + +依存関係として `pumpkin-api-zig` を追加します: + +```bash +zig fetch --save git+https://github.com/Pumpkin-MC/pumpkin-api-zig +``` + +プロジェクトルートに `build.zig` を作成します: + +```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. プラグインの記述 + +`src` ディレクトリを作成し、`src/main.zig` にコードを記述します: + +```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 = &.{"あなたの名前"}, + .description = "Zig言語によるサンプルプラグイン。", + }; + + pub const events = .{ + .player_join_event = onJoin, + }; + + pub fn onLoad(_: pumpkin.Context) !void { + std.log.info("Zigプラグインからこんにちは!", .{}); + } + + fn onJoin(_: pumpkin.Server, ev: *pumpkin.EventData(.player_join_event)) void { + std.log.info("{s} が参加しました", .{ev.player.getName()}); + } +}; + +comptime { + pumpkin.register(MyPlugin); +} +``` + +### 主な要素: +- **`std_options`**: `pumpkin.logFn` を介して、標準のZigログ出力 (`std.log`) をPumpkinのログシステムに転送します。 +- **`pub const metadata`**: コンポーネントの読み込み時にPumpkinが必要とするプラグイン情報 (名前、バージョン、作成者、説明) を定義します。 +- **`pub const events`**: イベントハンドラー (`.player_join_event` など) を登録します。 +- **`pub fn onLoad`**: Pumpkinがプラグインを初期化するときに呼び出されるエントリポイントです。 +- **`pumpkin.register(MyPlugin)`**: コンパイル時に必要なWebAssemblyコンポーネントのエクスポートとエントリポイントを生成します。 + +> [!NOTE] +> APIが返すものはすべて (ハンドルを含む)、現在のコールバックが終了するまでのみ有効です。ハンドルを保持したい場合は `keep()` を呼び出し、不要になったら `deinit()` で解放してください。 + +--- + +## 3. プラグインのビルド + +プラグインをWebAssemblyコンポーネントとしてコンパイルします: + +```bash +zig build +``` + +プロジェクトルートの `zig-out/my-zig-plugin.wasm` に生成されます。 + +--- + +## 4. プラグインの実行 + +1. 生成された `.wasm` ファイルをPumpkinサーバーの `plugins/` ディレクトリにコピーします: + ```bash + cp zig-out/my-zig-plugin.wasm /path/to/pumpkin/plugins/ + ``` +2. Pumpkinサーバーを起動または再起動します: + ```bash + ./pumpkin + ``` +3. サーバーログを確認して、プラグインが正常に読み込まれたことを確認します: + ```text + [INFO] Zigプラグインからこんにちは! + ``` diff --git a/docs/nl/plugin-dev/introduction.md b/docs/nl/plugin-dev/introduction.md index 3f05e45..ecf5eb1 100644 --- a/docs/nl/plugin-dev/introduction.md +++ b/docs/nl/plugin-dev/introduction.md @@ -8,7 +8,7 @@ Als je problemen ondervindt, neem dan contact op via [onze discord](https://disc Pumpkin Plugins integreren op een zeer diep niveau met de server software, waardoor veel dingen mogelijk zijn die op andere server software niet mogelijk zouden zijn. -De Pumpkin Plugin API haalt inspiratie uit de Spigot/Bukkit plugin API op veel plaatsen, dus als je eerdere ervaring hebt met deze en ervaring hebt met Rust, Python, C#, Go of C ontwikkeling, zou je vrij gemakkelijk plugins voor Pumpkin moeten kunnen schrijven :smile: +De Pumpkin Plugin API haalt inspiratie uit de Spigot/Bukkit plugin API op veel plaatsen, dus als je eerdere ervaring hebt met deze en ervaring hebt met Rust, Python, C#, Go, C, Kotlin, D of Zig ontwikkeling, zou je vrij gemakkelijk plugins voor Pumpkin moeten kunnen schrijven :smile: * [Rust API](https://github.com/Pumpkin-MC/Pumpkin) * [Python API](https://github.com/Pumpkin-MC/pumpkin-api-py) @@ -17,4 +17,5 @@ De Pumpkin Plugin API haalt inspiratie uit de Spigot/Bukkit plugin API op veel p * [C API](https://github.com/Pumpkin-MC/pumpkin-api-c) * [Kotlin API](https://github.com/Pumpkin-MC/pumpkin-api-kt) * [D API](https://github.com/Pumpkin-MC/pumpkin-api-d) +* [Zig API](https://github.com/Pumpkin-MC/pumpkin-api-zig) diff --git a/docs/nl/plugin-dev/zig/quick-start.md b/docs/nl/plugin-dev/zig/quick-start.md new file mode 100644 index 0000000..bd0d288 --- /dev/null +++ b/docs/nl/plugin-dev/zig/quick-start.md @@ -0,0 +1,122 @@ +# Quick Start + +Deze handleiding helpt je op weg met het schrijven van Pumpkin-serverplugins met de programmeertaal [Zig](https://ziglang.org/). + +Zig-plugins voor Pumpkin worden gecompileerd naar WebAssembly-componenten (Wasm) met behulp van de officiële [`pumpkin-api-zig`](https://github.com/Pumpkin-MC/pumpkin-api-zig) bindings. + +--- + +## Vereisten + +Voordat je Zig-plugins voor Pumpkin bouwt, zorg ervoor dat het volgende is geïnstalleerd: + +- **[Zig](https://ziglang.org/download/)**: Versie 0.16.0 of nieuwer. +- **[`wasm-tools`](https://github.com/bytecodealliance/wasm-tools)**: Beschikbaar in je `PATH` (gebruikt door het buildscript om WIT-metadata in te sluiten en het WebAssembly-component te genereren). + +--- + +## 1. Het project opzetten + +Maak een nieuwe map voor je pluginproject: + +```bash +mkdir my-zig-plugin +cd my-zig-plugin +``` + +Voeg `pumpkin-api-zig` toe als afhankelijkheid: + +```bash +zig fetch --save git+https://github.com/Pumpkin-MC/pumpkin-api-zig +``` + +Maak `build.zig` aan in de hoofdmap van het project: + +```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. De plugin schrijven + +Maak een map `src` aan en plaats je code in `src/main.zig`: + +```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 = &.{"JouwNaam"}, + .description = "Een voorbeeldplugin in Zig.", + }; + + pub const events = .{ + .player_join_event = onJoin, + }; + + pub fn onLoad(_: pumpkin.Context) !void { + std.log.info("Hallo vanuit Zig!", .{}); + } + + fn onJoin(_: pumpkin.Server, ev: *pumpkin.EventData(.player_join_event)) void { + std.log.info("{s} is binnengekomen", .{ev.player.getName()}); + } +}; + +comptime { + pumpkin.register(MyPlugin); +} +``` + +### Belangrijke onderdelen: +- **`std_options`**: Stuurt standaard Zig-logging (`std.log`) door naar het logsysteem van Pumpkin via `pumpkin.logFn`. +- **`pub const metadata`**: Definieert plugin-metadata (naam, versie, auteurs, beschrijving) die Pumpkin nodig heeft bij het laden van het component. +- **`pub const events`**: Registreert gebeurtenis-handlers (zoals `.player_join_event`). +- **`pub fn onLoad`**: Het toegangspunt dat wordt aangeroepen wanneer Pumpkin de plugin initialiseert. +- **`pumpkin.register(MyPlugin)`**: Genereert tijdens compilatietijd de benodigde WebAssembly-componentexports en toegangspunten. + +> [!NOTE] +> Alles wat de API retourneert (inclusief handles) is alleen geldig totdat de huidige callback retourneert. Roep `keep()` aan op een handle om deze te behouden, en geef deze weer vrij met `deinit()` als je klaar bent. + +--- + +## 3. De plugin bouwen + +Compileer je plugin naar een WebAssembly-component: + +```bash +zig build +``` + +Dit genereert `zig-out/my-zig-plugin.wasm` in je projectmap. + +--- + +## 4. De plugin uitvoeren + +1. Kopieer het gecompileerde `.wasm`-bestand naar de map `plugins/` van je Pumpkin-server: + ```bash + cp zig-out/my-zig-plugin.wasm /pad/naar/pumpkin/plugins/ + ``` +2. Start of herstart Pumpkin: + ```bash + ./pumpkin + ``` +3. Controleer de serverlogs om te bevestigen dat je plugin is geladen: + ```text + [INFO] Hallo vanuit Zig! + ``` diff --git a/docs/pt/plugin-dev/introduction.md b/docs/pt/plugin-dev/introduction.md index 5935b9b..1826e78 100644 --- a/docs/pt/plugin-dev/introduction.md +++ b/docs/pt/plugin-dev/introduction.md @@ -9,7 +9,7 @@ em [nosso servidor no Discord](https://discord.gg/aaNuD6rFEe). Os Plugins Pumpkin se integram ao software do servidor de maneira muito profunda, permitindo muitas coisas que não seriam possíveis em outros softwares de servidor. -A API de Plugins Pumpkin se inspira na API de plugins do Spigot/Bukkit em diversos aspectos, então, se você tem experiência prévia com os mesmos e possui experiência com desenvolvimento em Rust, Python, C#, Go ou C, você terá uma experiência relativamente fácil ao escrever plugins para o Pumpkin. :smile: +A API de Plugins Pumpkin se inspira na API de plugins do Spigot/Bukkit em diversos aspectos, então, se você tem experiência prévia com os mesmos e possui experiência com desenvolvimento em Rust, Python, C#, Go, C, Kotlin, D ou Zig, você terá uma experiência relativamente fácil ao escrever plugins para o Pumpkin. :smile: * [Rust API](https://github.com/Pumpkin-MC/Pumpkin) * [Python API](https://github.com/Pumpkin-MC/pumpkin-api-py) @@ -18,3 +18,4 @@ A API de Plugins Pumpkin se inspira na API de plugins do Spigot/Bukkit em divers * [C API](https://github.com/Pumpkin-MC/pumpkin-api-c) * [Kotlin API](https://github.com/Pumpkin-MC/pumpkin-api-kt) * [D API](https://github.com/Pumpkin-MC/pumpkin-api-d) +* [Zig API](https://github.com/Pumpkin-MC/pumpkin-api-zig) diff --git a/docs/pt/plugin-dev/zig/quick-start.md b/docs/pt/plugin-dev/zig/quick-start.md new file mode 100644 index 0000000..64fcc32 --- /dev/null +++ b/docs/pt/plugin-dev/zig/quick-start.md @@ -0,0 +1,122 @@ +# Início Rápido + +Este guia ajudará você a começar a criar plugins para o servidor Pumpkin utilizando a linguagem de programação [Zig](https://ziglang.org/). + +Os plugins em Zig para o Pumpkin são compilados em componentes WebAssembly (Wasm) utilizando os bindings oficiais [`pumpkin-api-zig`](https://github.com/Pumpkin-MC/pumpkin-api-zig). + +--- + +## Pré-requisitos + +Antes de iniciar, certifique-se de ter as seguintes ferramentas instaladas: + +- **[Zig](https://ziglang.org/download/)**: Versão 0.16.0 ou posterior. +- **[`wasm-tools`](https://github.com/bytecodealliance/wasm-tools)**: Disponível no seu `PATH` (usado pelo script de compilação para embutir os metadados WIT e gerar o componente WebAssembly). + +--- + +## 1. Configurando o Projeto + +Crie um novo diretório para o seu projeto de plugin: + +```bash +mkdir my-zig-plugin +cd my-zig-plugin +``` + +Adicione `pumpkin-api-zig` como dependência: + +```bash +zig fetch --save git+https://github.com/Pumpkin-MC/pumpkin-api-zig +``` + +Crie o arquivo `build.zig` na raiz do projeto: + +```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. Escrevendo o Plugin + +Crie o diretório `src` e adicione o seu código em `src/main.zig`: + +```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 = &.{"SeuNome"}, + .description = "Um exemplo de plugin em Zig.", + }; + + pub const events = .{ + .player_join_event = onJoin, + }; + + pub fn onLoad(_: pumpkin.Context) !void { + std.log.info("Olá do plugin em Zig!", .{}); + } + + fn onJoin(_: pumpkin.Server, ev: *pumpkin.EventData(.player_join_event)) void { + std.log.info("{s} entrou", .{ev.player.getName()}); + } +}; + +comptime { + pumpkin.register(MyPlugin); +} +``` + +### Elementos Chave: +- **`std_options`**: Redireciona os logs padrão do Zig (`std.log`) para o sistema de logs do Pumpkin através de `pumpkin.logFn`. +- **`pub const metadata`**: Define os metadados do plugin (nome, versão, autores, descrição) exigidos pelo Pumpkin ao carregar o componente. +- **`pub const events`**: Registra handlers de eventos (como `.player_join_event`). +- **`pub fn onLoad`**: Ponto de entrada invocado quando o Pumpkin inicializa o plugin. +- **`pumpkin.register(MyPlugin)`**: Gera em tempo de compilação as exportações e pontos de entrada necessários para o componente WebAssembly. + +> [!NOTE] +> Tudo o que a API retorna (incluindo identificadores/handles) é válido apenas até o retorno do callback atual. Chame `keep()` em um handle para mantê-lo e, em seguida, libere-o com `deinit()` quando terminar. + +--- + +## 3. Compilando o Plugin + +Compile o seu plugin como um componente WebAssembly: + +```bash +zig build +``` + +Isso gerará o arquivo `zig-out/my-zig-plugin.wasm` na raiz do seu projeto. + +--- + +## 4. Executando o Plugin + +1. Copie o arquivo `.wasm` gerado para a pasta `plugins/` do seu servidor Pumpkin: + ```bash + cp zig-out/my-zig-plugin.wasm /caminho/para/pumpkin/plugins/ + ``` +2. Inicie ou reinicie o servidor Pumpkin: + ```bash + ./pumpkin + ``` +3. Verifique os logs do servidor para confirmar o carregamento: + ```text + [INFO] Olá do plugin em Zig! + ``` diff --git a/docs/tr_TR/plugin-dev/introduction.md b/docs/tr_TR/plugin-dev/introduction.md index 6111ec6..0320d07 100644 --- a/docs/tr_TR/plugin-dev/introduction.md +++ b/docs/tr_TR/plugin-dev/introduction.md @@ -8,7 +8,7 @@ Herhangi bir sorunla karşılaşırsanız lütfen [Discord sunucumuzdan](https:/ Pumpkin Eklentileri, sunucu yazılımıyla çok derin bir seviyede entegre olur ve diğer sunucu yazılımlarında mümkün olmayacak birçok şeye olanak tanır. -Pumpkin Eklenti API'si birçok yerde Spigot/Bukkit eklenti API'sinden ilham alır; daha önce bunlarla deneyiminiz ve Rust, Python, C#, Go veya C geliştirme tecrübeniz varsa Pumpkin için eklenti yazmanız oldukça kolay olacaktır. :smile: +Pumpkin Eklenti API'si birçok yerde Spigot/Bukkit eklenti API'sinden ilham alır; daha önce bunlarla deneyiminiz ve Rust, Python, C#, Go, C, Kotlin, D veya Zig geliştirme tecrübeniz varsa Pumpkin için eklenti yazmanız oldukça kolay olacaktır. :smile: * [Rust API](https://github.com/Pumpkin-MC/Pumpkin) * [Python API](https://github.com/Pumpkin-MC/pumpkin-api-py) @@ -17,3 +17,4 @@ Pumpkin Eklenti API'si birçok yerde Spigot/Bukkit eklenti API'sinden ilham alı * [C API](https://github.com/Pumpkin-MC/pumpkin-api-c) * [Kotlin API](https://github.com/Pumpkin-MC/pumpkin-api-kt) * [D API](https://github.com/Pumpkin-MC/pumpkin-api-d) +* [Zig API](https://github.com/Pumpkin-MC/pumpkin-api-zig) diff --git a/docs/tr_TR/plugin-dev/zig/quick-start.md b/docs/tr_TR/plugin-dev/zig/quick-start.md new file mode 100644 index 0000000..7678eaf --- /dev/null +++ b/docs/tr_TR/plugin-dev/zig/quick-start.md @@ -0,0 +1,122 @@ +# Hızlı Başlangıç + +Bu kılavuz, [Zig programlama dilini](https://ziglang.org/) kullanarak Pumpkin sunucu eklentileri yazmaya başlamanıza yardımcı olacaktır. + +Pumpkin için Zig eklentileri, resmi [`pumpkin-api-zig`](https://github.com/Pumpkin-MC/pumpkin-api-zig) bağlamaları kullanılarak WebAssembly (Wasm) bileşenleri olarak derlenir. + +--- + +## Ön Koşullar + +Başlamadan önce aşağıdaki araçların kurulu olduğundan emin olun: + +- **[Zig](https://ziglang.org/download/)**: Sürüm 0.16.0 veya üzeri. +- **[`wasm-tools`](https://github.com/bytecodealliance/wasm-tools)**: `PATH` ortam değişkeninde mevcut olmalıdır (derleme betiği tarafından WIT meta verilerini gömmek ve WebAssembly bileşenini oluşturmak için kullanılır). + +--- + +## 1. Projeyi Kurma + +Eklenti projeniz için yeni bir dizin oluşturun: + +```bash +mkdir my-zig-plugin +cd my-zig-plugin +``` + +`pumpkin-api-zig` paketini bağımlılık olarak ekleyin: + +```bash +zig fetch --save git+https://github.com/Pumpkin-MC/pumpkin-api-zig +``` + +Proje kökünde `build.zig` dosyasını oluşturun: + +```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. Eklentiyi Yazma + +`src` dizinini oluşturun ve kodunuzu `src/main.zig` içine ekleyin: + +```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 = &.{"Adınız"}, + .description = "Zig dilinde örnek bir eklenti.", + }; + + pub const events = .{ + .player_join_event = onJoin, + }; + + pub fn onLoad(_: pumpkin.Context) !void { + std.log.info("Zig eklentisinden merhaba!", .{}); + } + + fn onJoin(_: pumpkin.Server, ev: *pumpkin.EventData(.player_join_event)) void { + std.log.info("{s} katıldı", .{ev.player.getName()}); + } +}; + +comptime { + pumpkin.register(MyPlugin); +} +``` + +### Önemli Bileşenler: +- **`std_options`**: `pumpkin.logFn` aracılığıyla standart Zig günlüklerini (`std.log`) Pumpkin günlük sistemine yönlendirir. +- **`pub const metadata`**: Bileşen yüklendiğinde Pumpkin tarafından gerekli görülen eklenti bilgilerini (ad, sürüm, yazarlar, açıklama) tanımlar. +- **`pub const events`**: Eklenti tarafından kaydedilen olay işleyicilerini (örneğin `.player_join_event`) tanımlar. +- **`pub fn onLoad`**: Pumpkin eklentiyi başlattığında çağrılan giriş noktasıdır. +- **`pumpkin.register(MyPlugin)`**: Derleme sırasında gerekli WebAssembly bileşeni dışa aktarımlarını ve giriş noktalarını üretir. + +> [!NOTE] +> API tarafından döndürülen her şey (tanıtıcılar/handles dahil), yalnızca geçerli geri arama (callback) dönene kadar geçerlidir. Bir tanıtıcıyı korumak için `keep()` işlevini çağırın ve işiniz bittiğinde `deinit()` ile serbest bırakın. + +--- + +## 3. Eklentiyi Derleme + +Eklentinizi bir WebAssembly bileşeni olarak derleyin: + +```bash +zig build +``` + +Bu komut proje kök dizininizde `zig-out/my-zig-plugin.wasm` dosyasını oluşturacaktır. + +--- + +## 4. Eklentiyi Çalıştırma + +1. Derlenen `.wasm` dosyasını Pumpkin sunucunuzun `plugins/` dizinine kopyalayın: + ```bash + cp zig-out/my-zig-plugin.wasm /yol/pumpkin/plugins/ + ``` +2. Pumpkin sunucusunu başlatın veya yeniden başlatın: + ```bash + ./pumpkin + ``` +3. Eklentinin yüklendiğini doğrulamak için sunucu günlüklerini kontrol edin: + ```text + [INFO] Zig eklentisinden merhaba! + ``` diff --git a/docs/zh_cn/plugin-dev/introduction.md b/docs/zh_cn/plugin-dev/introduction.md index b7d8044..0cc5b6f 100644 --- a/docs/zh_cn/plugin-dev/introduction.md +++ b/docs/zh_cn/plugin-dev/introduction.md @@ -7,7 +7,7 @@ Pumpkin 插件 API 仍处于非常早期的开发阶段,可能随时会发生 Pumpkin 插件与服务器软件在很深的层次上集成,允许实现其他服务器软件无法实现的许多功能。 -Pumpkin 插件 API 在很多方面受到 Spigot/Bukkit 插件 API 的启发,因此如果您有这些 API 的使用经验并且熟悉 Rust、Python、C#、Go 或 C 开发,您应该能够相对轻松地为 Pumpkin 编写插件。 :smile: +Pumpkin 插件 API 在很多方面受到 Spigot/Bukkit 插件 API 的启发,因此如果您有这些 API 的使用经验并且熟悉 Rust、Python、C#、Go、C、Kotlin、D 或 Zig 开发,您应该能够相对轻松地为 Pumpkin 编写插件。 :smile: * [Rust API](https://github.com/Pumpkin-MC/Pumpkin) * [Python API](https://github.com/Pumpkin-MC/pumpkin-api-py) @@ -16,3 +16,4 @@ Pumpkin 插件 API 在很多方面受到 Spigot/Bukkit 插件 API 的启发, * [C API](https://github.com/Pumpkin-MC/pumpkin-api-c) * [Kotlin API](https://github.com/Pumpkin-MC/pumpkin-api-kt) * [D API](https://github.com/Pumpkin-MC/pumpkin-api-d) +* [Zig API](https://github.com/Pumpkin-MC/pumpkin-api-zig) diff --git a/docs/zh_cn/plugin-dev/zig/quick-start.md b/docs/zh_cn/plugin-dev/zig/quick-start.md new file mode 100644 index 0000000..3a381ce --- /dev/null +++ b/docs/zh_cn/plugin-dev/zig/quick-start.md @@ -0,0 +1,122 @@ +# 快速入门 + +本指南将帮助你开始使用 [Zig 语言](https://ziglang.org/)编写 Pumpkin 服务器插件。 + +针对 Pumpkin 的 Zig 语言插件通过官方提供的 [`pumpkin-api-zig`](https://github.com/Pumpkin-MC/pumpkin-api-zig) 绑定编译为 WebAssembly(Wasm)组件。 + +--- + +## 前置要求 + +在构建 Zig 语言插件之前,请确保已安装以下工具: + +- **[Zig](https://ziglang.org/download/)**:0.16.0 或更高版本。 +- **[`wasm-tools`](https://github.com/bytecodealliance/wasm-tools)**:确保已存在于系统的 `PATH` 环境变量中(构建脚本使用它来嵌入 WIT 元数据并生成 WebAssembly 组件)。 + +--- + +## 1. 初始化项目 + +为你的插件项目创建一个新目录: + +```bash +mkdir my-zig-plugin +cd my-zig-plugin +``` + +获取并添加 `pumpkin-api-zig` 依赖: + +```bash +zig fetch --save git+https://github.com/Pumpkin-MC/pumpkin-api-zig +``` + +在项目根目录下创建 `build.zig`: + +```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. 编写插件代码 + +创建 `src` 目录并在 `src/main.zig` 中添加代码: + +```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 = &.{"你的名字"}, + .description = "Zig 语言编写的示例插件。", + }; + + pub const events = .{ + .player_join_event = onJoin, + }; + + pub fn onLoad(_: pumpkin.Context) !void { + std.log.info("来自 Zig 插件的问候!", .{}); + } + + fn onJoin(_: pumpkin.Server, ev: *pumpkin.EventData(.player_join_event)) void { + std.log.info("{s} 加入了游戏", .{ev.player.getName()}); + } +}; + +comptime { + pumpkin.register(MyPlugin); +} +``` + +### 关键要素: +- **`std_options`**:通过 `pumpkin.logFn` 将标准 Zig 日志(`std.log`)重定向到 Pumpkin 的日志系统。 +- **`pub const metadata`**:定义组件加载时 Pumpkin 所需的插件元数据(名称、版本、作者、描述)。 +- **`pub const events`**:定义插件注册的事件处理函数(例如 `.player_join_event`)。 +- **`pub fn onLoad`**:Pumpkin 初始化插件时调用的入口点。 +- **`pumpkin.register(MyPlugin)`**:在编译期生成所需的 WebAssembly 组件导出项与入口点。 + +> [!NOTE] +> API 返回的所有对象(包括句柄)仅在当前回调执行期间有效。若需保留句柄,请调用 `keep()`,并在使用完毕后通过 `deinit()` 释放。 + +--- + +## 3. 构建插件 + +将插件编译为 WebAssembly 组件: + +```bash +zig build +``` + +编译完成后,会在项目根目录生成 `zig-out/my-zig-plugin.wasm` 文件。 + +--- + +## 4. 运行插件 + +1. 将生成的 `.wasm` 文件复制到 Pumpkin 服务器的 `plugins/` 目录中: + ```bash + cp zig-out/my-zig-plugin.wasm /path/to/pumpkin/plugins/ + ``` +2. 启动或重启 Pumpkin 服务器: + ```bash + ./pumpkin + ``` +3. 查看控制台日志确认插件已成功加载: + ```text + [INFO] 来自 Zig 插件的问候! + ```