PotatoMC Native Plugin API
The high-performance Paper-grade native Rust plugin development kit for PotatoMC. Build ultra-fast native dynamic libraries (.so / .dll / .dylib) with zero JVM garbage-collection overhead.
Zero JNI bridge delay
vs 1.5GB JVM heap
Deterministic Rust drops
Native dialogs, PDC, forms
API Modules Directory
Click any module for code examples & signaturesLifecycle & Architecture
Understand the native .so / .dll dynamic library lifecycle and the Plugin trait entrypoints.
Event System
Register high-speed event handlers with priority execution, Cancellable traits, and zero GC.
Brigadier Commands
Fluent command tree builder, type-safe arguments, tab completion, and console/player dispatch.
Configuration API
Thread-safe YAML/TOML configuration parsing and automatic reloading mirroring Bukkit configs.
Scheduler API
Synchronous tick delays, repeating tasks, and async Rayon background worker threadpools.
PDC & Items
Persistent Data Container key-value tags directly on ItemStacks, entities, and world chunks.
Text & MiniMessage
Adventure component architecture, MiniMessage gradient tags, hover events, and clickable links.
Dialogs, Forms & Books
Native Java 26.2 modal dialogs, Bedrock crossplay forms (Simple/Modal/Custom), and virtual books.
Scoreboards & Teams
FastBoard-style zero-allocation sidebar lines, below-name health hearts, and team collision rules.
BossBar API
Server-side boss health bars with custom colors, segmented division notches, and player tracking.
Toast Notifications & Events
Advancement-style popup toasts (Task, Goal, Challenge), item cooldown sweeps, and game event packets.
GUI & Chest Menus
Declarative chest inventory menus, animated item slots, click filters, and cancellation handlers.
Custom Model Data & Items
Direct resource pack CustomModelData getters/setters, declarative ItemVariant templates, and registry.
NPC & Fake Players
Spawn fake player or mob NPCs, Mojang skin textures, poses, equipment, pathing, and click listeners.
Advanced Entity API
Control glowing outlines, invulnerability, gravity flags, scoreboard tags, and living entity cameras.
Raytracing & Targeting
Line-of-sight target block & entity detection, camera direction vectors, and AABB collision testing.
Sounds & Environment
Spatial and player audio playback, real & cosmetic lightning strikes, weather toggles, and world blocks.
Potions & Particles
Apply status potion effects with ambient flags, custom particles with count/offsets, and area clouds.
Paper Migration Guide
A comprehensive handbook mapping familiar Java/Paper idioms to PotatoMC Rust constructs.
Minecraft 26.2 Parity Matrix
Real-time live verification table tracking parity across all Minecraft subsystems and vanilla mobs.
Architectural Parity: Paper Java vs PotatoMC Native Rust
| Feature / Subsystem | Paper / Spigot (JVM) | PotatoMC Native API | Benefit |
|---|---|---|---|
| Plugin Compilation | Bytecode JAR (JVM classloader) | Native cdylib (.so / .dll / .dylib) | Executes directly on host CPU with zero interpreter overhead |
| Memory Management | Generational GC pauses (ZGC / G1GC) | Deterministic compile-time RAII drops | Zero stop-the-world hitches; stable 20.0 TPS under heavy load |
| Event Dispatch | Reflection method invokes & object allocation | Direct function pointer execution | <0.05 microsecond latency per registered event listener |
| Concurrency & Threads | Single main server tick loop + Bukkit async | Work-stealing Rayon pipeline & safe mutexes | Native multi-core parallelism without race conditions |
| Interactive UI | Chest inventory GUI hacks & title packets | 26.2 Modal Dialogs + Bedrock Forms + Books | Rich client popups, forms, toggles, and crossplay menus |
Quick Start: Scaffold Your First Native Plugin
No Git clone required — one command setupcurl -sSL https://raw.githubusercontent.com/Flaxa-Technologies/potato-api/main/scripts/create-plugin.sh | bash -s MyAwesomePlugin "Flaxa Studios" linuxAI Assistant Native Context Bundling
Every scaffolded PotatoMC plugin project automatically comes equipped with pre-compiled AGENT.md and CLAUDE.md instruction contexts. When opening your plugin in Cursor, Claude Code, GitHub Copilot, or Antigravity, your AI assistant will instantly understand:
- ❯All 26 PotatoMC event signatures & Cancellable traits
- ❯Correct .cdylib crate typing and cross-compilation targets
- ❯Scoreboard, Dialog, BossBar, and PDC API builders
- ❯Common Java Bukkit idioms mapped to safe Rust alternatives