{"id":42985769,"url":"https://github.com/bedrock-mc/plugin","last_synced_at":"2026-01-31T02:20:12.632Z","repository":{"id":323403847,"uuid":"1093097405","full_name":"bedrock-mc/plugin","owner":"bedrock-mc","description":"Plugins for dragonfly in any language!","archived":false,"fork":false,"pushed_at":"2025-12-09T11:22:20.000Z","size":2527,"stargazers_count":10,"open_issues_count":7,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-11T15:39:37.673Z","etag":null,"topics":["df-mc","go","golang","mcpe","minecraft","php"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bedrock-mc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-11-09T22:20:46.000Z","updated_at":"2025-12-16T02:23:04.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bedrock-mc/plugin","commit_stats":null,"previous_names":["secmc/plugin","bedrock-mc/plugin"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/bedrock-mc/plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bedrock-mc%2Fplugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bedrock-mc%2Fplugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bedrock-mc%2Fplugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bedrock-mc%2Fplugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bedrock-mc","download_url":"https://codeload.github.com/bedrock-mc/plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bedrock-mc%2Fplugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28926710,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-30T22:32:35.345Z","status":"online","status_checked_at":"2026-01-31T02:00:09.179Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["df-mc","go","golang","mcpe","minecraft","php"],"created_at":"2026-01-31T02:20:11.442Z","updated_at":"2026-01-31T02:20:12.603Z","avatar_url":"https://github.com/bedrock-mc.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Dragonfly Plugin System\n\nWrite plugins for your Minecraft Bedrock server in any language, built on top of the [Dragonfly](https://github.com/df-mc/dragonfly) server software.\n\n## Why Dragonfly Plugins?\n\n| Benefit | Description |\n| --- | --- |\n| 🌍 **Any Language** | JavaScript, TypeScript, PHP, Python, Rust, C++, Go—if it can speak gRPC, it can be a plugin. |\n| 💰 **Sell Plugins** | Compile to a binary (Rust, Go, C++) and ship closed-source builds. |\n| 🔥 **Hot Reload** | Edit JS/TS/PHP plugins while the server runs; changes apply immediately. |\n| 📱 **Remote Control** | Plugins connect over gRPC, so you can run them on your phone, a web app, or a remote service. |\n| 📦 **Use Any Library** | Mix npm packages, Python ML libs, or anything else your runtime supports. |\n| ⚡ **Zero Performance Impact** | Plugins live in separate processes, so heavy work never blocks Dragonfly’s TPS. |\n| 🚀 **High Performance (SOON)** | The protocol is optimized protobuf with room for batching. |\n| 🔒 **Sandboxing** | Grant only the permissions each plugin needs over the gRPC interface. |\n\n### Real-World Examples\n\n```bash\n# Hot reload: Edit plugin code while server is running\nvim plugins/my-plugin.js   # Make changes\n# Changes apply immediately - no restart!\n\n# Remote plugin: Control server from your phone\n# Plugin runs on your phone, connects to server over internet\nphone-app → [gRPC] → Dragonfly Server\n\n# Binary plugin: Sell without source code\nrustc plugin.rs --release   # Compile to binary\n# Distribute the binary - customers can't see your code\n```\n\n## Key Features\n\n- **Event-driven API**: Subscribe to joins, chat, commands, block events, and more.\n- **Generated types**: Proto definitions live in `proto/types/` with generated Go + TypeScript stubs under `proto/generated/`.\n- **Language samples**: TypeScript, Node, PHP, and more under `examples/plugins/` to kick-start new plugins.\n- **Automation ready**: `make proto` (buf + scripts) and `make run` wire up the host for you.\n\n## How It Works\n\n```\n┌─────────────────┐         gRPC Stream          ┌──────────────────┐\n│                 │ ←──────────────────────────→ │                  │\n│  Dragonfly      │   Events: JOIN, CHAT, etc.   │  Your Plugin     │\n│  Server (Go)    │   Actions: TELEPORT, etc.    │  (Any Language)  │\n└─────────────────┘                              └──────────────────┘\n```\n\n1. **Server starts** and loads plugin configuration from `cmd/plugins/plugins.yaml`.\n2. **Plugin process launches** via the configured command (for example `node plugin.js`).\n3. **Handshake** occurs where the plugin registers its metadata and commands.\n4. **Plugin subscribes** to the events it wants.\n5. **Events flow** from Dragonfly to the plugin in real time.\n6. **Plugin executes actions** by sending protobuf messages back to the host.\n\n## Prerequisites\n\n- Go 1.22+ with `GOBIN` on your `PATH`.\n- [buf](https://buf.build/docs/cli/installation/) and `protoc-gen-go` (`go install google.golang.org/protobuf/cmd/protoc-gen-go@latest`).\n\n## Quick Start\n\n1. **Clone \u0026 bootstrap**\n   ```bash\n   git clone https://github.com/bedrock-mc/plugin.git\n   cd plugin\n   go mod download\n   make proto\n   ```\n2. **Configure a plugin** in `cmd/plugins/plugins.yaml`:\n   ```yaml\n   plugins:\n     - id: example-typescript\n       name: Example TypeScript Plugin\n       command: \"npm\"\n       args: [\"run\", \"dev\", \"--prefix\", \"examples/plugins/typescript\"]\n       address: \"unix:///tmp/dragonfly_plugin.sock\"\n   ```\n3. **Run the host**\n   ```bash\n   make run\n   ```\n4. **Iterate in your language** – edit the example plugin, or point the config at your own command/binary.\n\n## Building Plugins\n\n1. Copy an example from `examples/plugins/` or start fresh with `proto/types/plugin.proto`.\n2. Run `make proto` (or `buf generate` with your template) to refresh client stubs.\n3. Add your command + args + socket info to `cmd/plugins/plugins.yaml`.\n4. Implement the handshake: reply to `PluginHello`, register commands, then send `EventSubscribe`.\n5. Handle streamed events and reply with `ActionBatch` or `EventResult` messages. Because plugins speak gRPC, they can run locally, over loopback TCP, or on a remote machine.\n\n## Development Workflow\n\n```bash\nmake proto        # regenerate protobuf artifacts + post-gen scripts\ngo test ./...     # run all Go suites\nmake run          # launch Dragonfly host with sample config\nnpm run dev --prefix examples/plugins/typescript   # TypeScript live dev\nexamples/plugins/php/bin/php7/bin/php examples/plugins/php/src/HelloPlugin.php   # PHP sample\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbedrock-mc%2Fplugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbedrock-mc%2Fplugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbedrock-mc%2Fplugin/lists"}