Skip to main content

Minestrapper

A bootstrapper for Minecraft Java Edition Servers

About

Rather than building full Java plugins or mods, this project lets you tap into the server’s state and other lifecycle events, and add custom functionality directly in Python.

That means small features can be added without the overhead of a mod loader (e.g. Fabric, Forge) or plugin loader (e.g. Paper, Spigot), while keeping the server in its vanilla form.

Current Features

  • Config Handling
    • Contains a class for managing configuration files of both Minestrapper and Minecraft.
    • Minestrapper config uses a file named Config.json in a /minestrapper directory relative to the root of the Minecraft Server.
    • Allows for direct editing of server.properties.
  • State Handling
    • Contains a class for getting the current state of the server based on the server output.
    • Tracks the following states: STARTING, RUNNING, PAUSED, STOPPING, STOPPED.
  • New Line Callbacks
    • A lifecycle function that runs everytime a new line is sent from the Minecraft Server process
  • Logger
    • Prints out stuff both from forwarding logs from the Minecraft process and also custom logs from Minestrapper.
    • Keeps Minestrapper specific logs visually consistent with Minecraft Server logs (e.g. "[19:48:06] [Minestrapper/INFO]: Initialized Minestrapper Logger successfully")
    • Logs to a file named latest-minestrapper.log and then replaces the vanilla latest.log with it when the server stops.
    • Provides transformers to modify each logged line to the output as needed.
  • Built-in features:
    • "State Styles"
      • Updates the terminal title and text color based on the server's current state.
      • Makes it easier to see whether the server is starting, running, paused, stopping, or stopped.
    • "Server Resource Pack"
      • Includes a lightweight HTTP server for serving a server resource pack.
      • Removes the need for an external hosting site for the pack.
      • Keeps resource pack delivery self-contained within the server setup.

Potential Future Features

  • Backups: Let the owner integrate save backups everytime the server closes locally. It can either be done locally only, with cloud services, or even both.
  • Remote Panels: Allow the owner along with anyone else authorized to remotely turn on and off the server. Only the owner will be able to view logs and run commands however.
  • Custom Commands: Add your own admin commands that can trigger multiple Minecraft commands or even run Python code.

Installation Guide

  1. Install Python at https://www.python.org/ (>=3.1).
  2. Go to your Minecraft Server directory.
  3. Make a directory exactly named minestrapper and change directory to it.
mkdir minestrapper && cd minestrapper
  1. Make a new Python environment.

Windows:

python -m venv .venv

MacOS / Linux:

python3 -m venv .venv
  1. Activate the environment.

Windows:

.\.venv\Scripts\activate

MacOS / Linux:

source .venv/bin/activate
  1. Install the minestrapper package.
pip install minestrapper
  1. Create a file exactly named Config.json and edit to your liking.
{
  "$schema": "https://faizaan-j.github.io/mine-strapper/schemas/Config.schema.json"
}
  1. Make an entry point file inside the minestrapper directory.

main.py

Example:

from pathlib import Path

from minestrapper import Server

if __name__ == "__main__":
    server = Server(path=Path.cwd().parent)
    server.start_server()

    server.wait_loop()

Optional:

Create an executable script to facilitate starting the server.

Windows:

Place start.bat in the root of the Minecraft Server

@echo off

cd minestrapper
call .\.venv\Scripts\Activate
python main.py

MacOS / Linux:

  1. Place start.sh in the root of the Minecraft Server
#!/bin/bash

cd minestrapper
source .venv/bin/activate
python main.py
  1. Open the terminal in the same directory and make the shell script executable.
chmod +x start.sh

Important Notes

  • You still need to do any necessary port forwarding yourself.
  • Minestrapper has only been tested on modern versions of Minecraft. However, the estimated minimum version that this should work is Java Edition 1.7.2

License

MineStrapper is released under the MIT License.
Feel free to use, modify, and share.

Metadata

Release files for minestrapper 0.3.8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for minestrapper 0.3.8
File Size Uploaded Provenance Actions
minestrapper-0.3.8.tar.gz 15.0 kB Without provenance Details for minestrapper-0.3.8.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for minestrapper 0.3.8
File Interpreter ABI Platform Actions
minestrapper-0.3.8-py3-none-any.whl Python 3 none any Details for minestrapper-0.3.8-py3-none-any.whl

Total release size: 32.4 kB

Release files / minestrapper-0.3.8.tar.gz

Download URL minestrapper-0.3.8.tar.gz
Size 15.0 kB
Tags Source
SHA-256 checksum
How to use checksums
bdfeb3643069e92c573a4421e1f990d6eaec0f6102f005e896b4b550abfd589a
BLAKE2b-256 checksum
How to use checksums
decaaf6b7258ec69772e1105d1e767dfac2c0a20a8e2bf40c6e699c07ad732bc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.10.8

Release files / minestrapper-0.3.8-py3-none-any.whl

Download URL minestrapper-0.3.8-py3-none-any.whl
Size 17.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
28764f13744411c8dee47d93d1518f438e4e7be3a93ecd75889fdfb8258ad7fc
BLAKE2b-256 checksum
How to use checksums
0f090b1eda17c73053e97ac9e6f1d4d954d20bca92fb5a469722d49fd8253a82
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.10.8

Security for minestrapper 0.3.8

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page