A starter template for building Endstone plugins in Python. Endstone is a plugin framework for Minecraft Bedrock Dedicated Server, similar to Bukkit/Spigot/Paper for Java Edition. This template demonstrates commands, events, configuration, and permissions.
- Click Use this template on GitHub (or fork/clone it)
- Rename the following to match your plugin:
| What | Where | Example |
|---|---|---|
| Package name | pyproject.toml [project] name |
endstone-my-plugin |
| Package directory | src/endstone_example/ |
src/endstone_my_plugin/ |
| Entry point | pyproject.toml [project.entry-points."endstone"] |
my-plugin = "endstone_my_plugin:MyPlugin" |
| Plugin class | plugin.py class name + prefix |
MyPlugin, prefix = "MyPlugin" |
| Permission prefix | plugin.py permissions dict keys |
my_plugin.command.* |
- Set
api_version = "0.11"(or the Endstone version you target) - Delete the example command/listener code and start building
This template uses uv for fast dependency management. If you
prefer pip, replace uv sync with pip install -e ".[dev]" and uv run with just running
the command directly.
git clone https://github.com/EndstoneMC/python-example-plugin.git
cd python-example-plugin
uv sync --extra dev # Install dependencies
uv run ruff check src/ # LintFor live development on a running server, activate the server's virtualenv and install in editable mode:
pip install -e .Then use /reload in-game to pick up code changes without restarting.
src/endstone_example/
__init__.py Re-exports the plugin class
plugin.py Plugin lifecycle, commands, config
listener.py Event listener (player join/quit)
config.toml Default config (copied on first run)
To use third-party packages from PyPI, add them to the dependencies list in pyproject.toml:
[project]
dependencies = ["requests>=2.31", "aiosqlite>=0.19"]Then run uv sync (or pip install -e .) to install them. They will be bundled automatically
when you build the wheel.
uv buildCopy the .whl from dist/ into your server's plugins/ folder and restart.
This template includes a GitHub Actions release workflow. To make a release:
- Add your changes under
## [Unreleased]inCHANGELOG.md - Go to Actions > Release > Run workflow
- Enter the version (e.g.
0.5.0) and run
The workflow validates the version, updates the changelog, creates a git tag and GitHub release,
builds the wheel, publishes to PyPI (if configured), and attaches the .whl to the release.
Use dry run to preview without making changes.
Versioning is handled automatically by hatch-vcs: tagged
commits get clean versions (e.g. 0.5.0), untagged commits get dev versions
(e.g. 0.5.1.dev3).
For more on the Endstone API, see the documentation.