BedrioxDOCUMENTATION
PLUGIN DEVELOPMENT · GETTING STARTED

Build your first plugin.

Start from working first-party source, use the matching API, and package it with PluginTools.

FROM THE SCANNED EXAMPLE

How a plugin is laid out

This tree is generated from the exact ExamplePlugin revision used for this documentation. Keep the manifest at the project root and put namespaced PHP classes under src/.

PROJECT TREE
ExamplePlugin/
├── plugin.json
├── composer.json
├── src/
│   ├── Command/
│   │   ├── DisplayMode.php
│   │   ├── ExampleBroadcastCommand.php
│   │   ├── ExampleDisplayCommand.php
│   │   ├── ExampleEffectCommand.php
│   │   ├── ExampleSenderCommand.php
│   │   └── ExampleSpawnCommand.php
│   ├── Entity/
│   │   ├── ExampleMobBehavior.php
│   │   └── ExampleMobStateCodec.php
│   └── Main.php
├── resources/
│   └── config.yml
└── tests/

plugin.json

Declares the plugin name, version, compatible API range, entry class, namespace, dependencies, and load phase.

src/Main.php

Your entry class extends Plugin. Bedriox creates it and calls its lifecycle methods.

resources/

Package default configuration and other server-side files here. Bedriox copies editable files into the plugin data directory.

src/Command/ and other folders

Organize commands, listeners, entities, and other classes beneath the namespace declared by the manifest.

tests/

Keep automated checks beside the plugin project so behavior can be verified before packaging a PHAR.

Read the manifest

This is the real plugin.json from that same scanned revision:

JSON
{
  "schema": 1,
  "name": "ExamplePlugin",
  "version": "0.1.0",
  "api": "^0.4",
  "main": "Bedriox\\ExamplePlugin\\Main",
  "namespace": "Bedriox\\ExamplePlugin",
  "authors": ["Bedriox Team"],
  "dependencies": [],
  "softDependencies": [],
  "load": "WORLD_READY"
}

Bedriox plugins are trusted PHP programs that run inside the server process. Start with the first-party ExamplePlugin, keep work bounded, and use only the public Bedriox\Api surface documented here.

Player, world, inventory, and entity objects are authoritative server capabilities rather than ordinary mutable data. Register commands, event subscribers, recipes, and custom entities from onEnable(), and keep callbacks short enough that they cannot stall the server tick.

What you need

  • A 64-bit PHP 8.4 or newer installation within the PHP 8 major line.
  • Composer 2.
  • A Bedriox checkout or release matching the documentation version you select.
  • PluginTools when developing a source plugin or building a signed PHAR.

First steps

  1. Download the version-matched ExamplePlugin source and the latest PluginTools.phar using the buttons above.
  2. Extract ExamplePlugin into the server's plugins/ directory and place PluginTools.phar beside it.
  3. Review plugin.json, especially its name, version, API range, main class, namespace, dependencies, and load phase.
  4. Restart Bedriox so PluginTools can register the complete source definition.
  5. Change one listener or command, run the plugin repository checks, and restart again before testing loaded class changes.
  6. Build a signed PHAR with makeplugin ExamplePlugin when the plugin is ready.

Build the PHAR

Run makeplugin ExamplePlugin from the server console. PluginTools validates the source definition and packages it for distribution. Keep the generated checksum with the PHAR when publishing a release.

Choose the right documentation

Use the version picker in the documentation header. API pages identify the exact Bedriox and ExamplePlugin commits used to generate them. Direct packet access is version-specific; prefer high-level player, world, inventory, command, event, and scheduler APIs whenever possible.