Skip to content

Commit 660c908

Browse files
committed
Add sample plugin
1 parent ef6003d commit 660c908

7 files changed

Lines changed: 204 additions & 2 deletions

File tree

‎.github/workflows/build.yml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# This workflow will install Python dependencies and run tests with a variety of Python versions
2+
# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
3+
4+
name: Build
5+
6+
on:
7+
push:
8+
branches: [ "main" ]
9+
pull_request:
10+
branches: [ "main" ]
11+
12+
jobs:
13+
build:
14+
runs-on: ubuntu-latest
15+
strategy:
16+
fail-fast: false
17+
matrix:
18+
python-version: [ "3.9", "3.10", "3.11", "3.12" ]
19+
20+
steps:
21+
- name: Checkout Code
22+
uses: actions/checkout@v4
23+
24+
- name: Set up Python ${{ matrix.python-version }}
25+
uses: actions/setup-python@v5
26+
with:
27+
python-version: ${{ matrix.python-version }}
28+
29+
- name: Install
30+
run: |
31+
python -m pip install --upgrade pip
32+
pip install .

‎.github/workflows/publish.yml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# This workflow will publish a Python Package to PyPI when a release is created
2+
# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
3+
4+
name: Publish
5+
6+
on:
7+
release:
8+
types: [ published ]
9+
10+
permissions:
11+
contents: read
12+
13+
jobs:
14+
publish:
15+
if: github.repository == 'EndstoneMC/python-plugin-template'
16+
runs-on: ubuntu-latest
17+
environment: pypi
18+
permissions:
19+
id-token: write
20+
contents: write
21+
steps:
22+
- name: Checkout Code
23+
uses: actions/checkout@v4
24+
25+
- name: Build sdist
26+
run: pipx run build --sdist
27+
28+
- name: Publish to PyPI
29+
uses: pypa/gh-action-pypi-publish@release/v1

‎.gitignore‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -157,4 +157,7 @@ cython_debug/
157157
# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
158158
# and can be added to the global gitignore or merged into this file. For a more nuclear
159159
# option (not recommended) you can uncomment the following to ignore the entire idea folder.
160-
#.idea/
160+
.idea/
161+
162+
# Wheels
163+
wheelhouse/

‎CHANGELOG.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6+
and this project adheres to [PEP 440 Versioning](https://peps.python.org/pep-0440/).
7+
8+
## [0.1.0] - 2024-01-30
9+
10+
### Added
11+
12+
- Sample python plugin with `on_load`, `on_enable` and `on_disable` callback methods.
13+
- Add GitHub Actions for build and publish python package.
14+
15+
[unreleased]: https://github.com/EndstoneMC/python-plugin-template/compare/v0.1.0...HEAD
16+
17+
[0.1.0]: https://github.com/EndstoneMC/python-plugin-template/releases/tag/v0.1.0

‎README.md‎

Lines changed: 74 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,74 @@
1-
# python-plugin-template
1+
# Endstone Python Plugin Template
2+
3+
Welcome to the official Python plugin template for Endstone. This repository provides a basic structure and a sample
4+
plugin to help developers start writing plugins for the Bedrock Dedicated Servers in Python using the Endstone API.
5+
6+
## Prerequisites
7+
8+
- Python 3.9 or higher.
9+
- Endstone installed and set up in your Python environment.
10+
11+
## Structure Overview
12+
13+
```
14+
python-plugin-template/
15+
├── src/ # Main source directory
16+
│ └── endstone_plugin/ # Directory for the plugin package
17+
│ └── __init__.py # Initializer for the package, containing SamplePlugin class
18+
├── .gitignore # Git ignore rules
19+
├── CHANGELOG.md # Changelogs
20+
├── LICENSE # License details
21+
├── README.md # This file
22+
└── pyproject.toml # Plugin configuration file
23+
```
24+
25+
## Getting Started
26+
27+
1. **Clone this Repository**
28+
29+
```bash
30+
git clone https://github.com/EndstoneMC/python-plugin-template.git
31+
```
32+
33+
2. **Navigate to the Cloned Directory**
34+
35+
```bash
36+
cd python-plugin-template
37+
```
38+
39+
3. **Configurate**
40+
1. Open the `pyproject.toml` and change the `name` under the `[project]` section from `endstone-plugin` to your own
41+
name for your plugin.
42+
2. Rename the folder `src/endstone_plugin` to `src/{your_plugin_name}`.
43+
3. Rename the `PythonSamplePlugin` class within `src/{your_plugin_name}/__init__.py` to, for example.
44+
4. Open the `pyproject.toml` again and update the entrypoint under the `[project.entry-points."endstone"]` section.
45+
46+
4. **Test Your Plugin**
47+
48+
When developing the plugin, you may want to install an editable package to your Python environment, this allows you
49+
to update the codes without having to reinstall the package everytime:
50+
```bash
51+
pip install -e .
52+
```
53+
**NOTE: It is strongly recommended to create a virtual environment for your Endstone server and plugins. When
54+
installing your plugin using `pip install`, please ensure the virtual environment is activated.**
55+
56+
Ensure your plugin is loaded correctly by checking the server logs or console for the log messages.
57+
58+
5. **Package and Distribute Your Plugin**
59+
60+
When everything is good to go, you can package your plugin into a `.whl` (Wheel) file for easier distribution:
61+
62+
```bash
63+
pip install wheel
64+
python -m pip wheel . --no-deps --wheel-dir=wheelhouse
65+
```
66+
67+
This command will produce a `.whl` file in the `wheelhouse` directory which can be installed. To publish your plugin
68+
to a package index such as PyPI, please refer to:
69+
- [Using TestPyPI](https://packaging.python.org/en/latest/guides/using-testpypi/)
70+
- [Publishing package distribution releases using GitHub Actions CI/CD workflows](https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/)
71+
72+
## License
73+
74+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

‎pyproject.toml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
[build-system]
2+
requires = ["setuptools >= 61.0"]
3+
build-backend = "setuptools.build_meta"
4+
5+
[project]
6+
name = "endstone-plugin"
7+
version = "0.1.0"
8+
dependencies = [
9+
"endstone",
10+
]
11+
requires-python = ">=3.9"
12+
authors = [
13+
{ name = "Endstone Developers", email = "hello@endstone.dev" },
14+
]
15+
maintainers = [
16+
{ name = "Vincent Wu", email = "magicdroidx@gmail.com" },
17+
{ name = "Endstone Developers", email = "hello@endstone.dev" }
18+
]
19+
description = "Official Python plugin template for Endstone servers"
20+
readme = "README.md"
21+
license = { file = "LICENSE" }
22+
keywords = ["endstone", "plugin"]
23+
classifiers = [
24+
"Development Status :: 3 - Alpha",
25+
"Programming Language :: Python"
26+
]
27+
28+
[project.urls]
29+
Homepage = "https://github.com/EndstoneMC/python-plugin-template"
30+
Documentation = "https://readthedocs.org"
31+
Repository = "https://github.com/EndstoneMC/python-plugin-template.git"
32+
Issues = "https://github.com/EndstoneMC/python-plugin-template/issues"
33+
Changelog = "https://github.com/EndstoneMC/python-plugin-template/blob/main/CHANGELOG.md"
34+
35+
[project.entry-points."endstone"]
36+
endstone_plugin = "endstone_plugin:PythonSamplePlugin"

‎src/endstone_plugin/__init__.py‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
from endstone.plugin import Plugin
2+
3+
4+
class PythonSamplePlugin(Plugin):
5+
def on_load(self) -> None:
6+
self.logger.info("on_load is called!")
7+
8+
def on_enable(self) -> None:
9+
self.logger.info("on_enable is called!")
10+
11+
def on_disable(self) -> None:
12+
self.logger.info("on_disable is called!")

0 commit comments

Comments
 (0)