Expose Bukkit APIs to Python scripts via easy-to-use wrappers
PyJavaBridge
PyJavaBridge is a Minecraft server plugin that lets you write Python scripts that interact with the Bukkit/Spigot/Paper API through a high-level async bridge. Every API call is asynchronous under the hood — you write clean async/await Python and the bridge handles the Java ↔ Python communication transparently.
Quick Start
from bridge import *
@command("Say hello")
async def hello(event: Event):
await event.player.send_message("Hello from Python!")
Drop your .py file into the server's scripts/ folder and reload. The bridge discovers your @command and @event handlers automatically.
Key Features
- Full Bukkit API — Players, worlds, blocks, entities, inventories, scoreboards, boss bars, advancements, and more.
- Async by default — All Java calls are awaitable. Use
async/await naturally.
- Decorator-driven — Register commands, events, and repeating tasks with simple decorators.
- Helper classes —
ItemBuilder, Sidebar, Hologram, Menu, Cooldown, Config, and display entities for common patterns.
- Region utilities — Fill, replace, and shape operations on the world (spheres, cylinders, lines).
- Particle shapes — Draw particle lines, spheres, cubes, and rings with one call.
- Permission integration — LuckPerms-aware permission and group management.
- Tab list control — Full control over player tab list headers, footers, and display names.
Pages
Decorators & Core
Server & Entities
| Page |
Description |
| Server |
Global server API |
| Entity |
Base entity proxy |
| Player |
Player API (extends Entity) |
World & Space
| Page |
Description |
| World |
World API, region utilities, particle shapes, spawn helpers |
| Location |
3D position with world, yaw, and pitch |
| Block |
Block in the world |
| Chunk |
World chunk loading/unloading |
| Vector |
3D vector |
Items & Inventory
Effects & Attributes
Scoreboards & UI
Helpers
Display Entities
Utilities
| Page |
Description |
| Raycast |
Ray tracing in the world |
| Chat |
Chat broadcast helper |
| Reflect |
Java reflection access |
| Enums |
All enum types |
Extensions ext
Extensions are imported separately via from bridge.extensions import ....
Examples
| Page |
Description |
| Examples |
Full script examples |
Internals
| Page |
Description |
| Bridge |
Overview of the bridge architecture and wire protocol |
| Events |
Event subscriptions, dispatch, cancellation, overrides, and commands |
| Execution |
Call dispatch, threading, timing, and batching |
| Serialization |
Object handles, type serialization, and proxy classes |
| Lifecycle |
Startup, shutdown, and hot reload |
| Debugging |
Debug logging, metrics, error codes, and performance tips |