Python MC Mod

PythonMC

PythonMC is a server-side Fabric mod that adds lightweight Python scripting to Minecraft 1.21.1.

It lets server owners write simple Python scripts for common automation, player messages, server events, and command-driven behavior without recompiling the mod.

Features

- Loads Python scripts from the server config folder. - Starts and manages a local Python 3.8+ script host automatically. - Provides server lifecycle, tick, and player connection events. - Exposes a small API for logging, broadcasting, private messages, and server command execution. - Includes `/pythonmc` admin commands for status, reloads, restarts, custom events, and quick Python snippets. - Ships with an example script on first launch.

Requirements

- Minecraft 1.21.1 - Fabric Loader 0.18.4 or newer - Fabric API - Java 21 - Python 3.8 or newer installed on the server

Python must be available as `python3` or `python` on the server `PATH`.

If Python is installed somewhere else, set one of these before launching Minecraft:

```text -Dpythonmc.python=/path/to/python ```

or:

```text PYTHONMC_PYTHON=/path/to/python ```

Installation

1. Install Fabric Loader for Minecraft 1.21.1. 2. Install Fabric API. 3. Put the PythonMC jar in the server `mods` folder. 4. Make sure Python 3.8+ is installed on the machine running the server. 5. Start the server once.

PythonMC will create this folder:

```text config/pythonmc/scripts ```

It will also create a starter script:

```text config/pythonmc/scripts/main.py ```

Writing Scripts

Scripts are normal `.py` files inside:

```text config/pythonmc/scripts ```

Files whose names start with `_` are ignored. After editing scripts, reload them in-game or from the server console:

```text /pythonmc reload ```

Basic example:

```python import pythonmc_api as mc

def on_server_started(ctx): mc.log("PythonMC script loaded.")

def on_player_join(ctx): mc.tell(ctx["name"], "Welcome! This message came from PythonMC.") ```

Script API

Import the bundled API like this:

```python import pythonmc_api as mc ```

Available functions:

```python mc.log(message, level="info") mc.broadcast(message) mc.tell(player_name, message) mc.execute(command) ```

`mc.execute(command)` runs a Minecraft server command as the server command source. Use it carefully.

Events

PythonMC calls functions in your scripts when matching events happen.

Supported event handlers:

```python def on_server_started(ctx): ... def on_server_stopping(ctx): ... def on_server_tick(ctx): ... def on_player_join(ctx): ... def on_player_leave(ctx): ... def on_shutdown(ctx): ... def on_event(event_name, ctx): ... ```

The `ctx` object contains event data. It supports both dictionary-style access and `.get()`:

```python def on_player_join(ctx): player_name = ctx["name"] player_uuid = ctx.get("uuid") ```

Common player event fields:

```text name uuid ```

Common server event fields:

```text players max_players tick scripts_dir ```

Commands

All commands require permission level 4.

```text /pythonmc status /pythonmc start /pythonmc stop /pythonmc restart /pythonmc reload /pythonmc py <python code> /pythonmc event <event_name> ```

Command details:

- `/pythonmc status` shows whether the Python host is running and where scripts are loaded from. - `/pythonmc start` starts the Python script host if it is stopped. - `/pythonmc stop` stops the Python script host. - `/pythonmc restart` restarts the Python script host. - `/pythonmc reload` reloads scripts from `config/pythonmc/scripts`. - `/pythonmc py <python code>` runs a Python snippet in the host process. - `/pythonmc event <event_name>` sends a custom event to scripts.

Custom event example:

```python import pythonmc_api as mc

def on_event(event_name, ctx): if event_name == "maintenance": mc.broadcast("Server maintenance is starting soon.") ```

Then run:

```text /pythonmc event maintenance ```

Security Notes

PythonMC scripts run on the server machine with the permissions of the Minecraft server process.

Only install or write scripts you trust. A Python script can perform normal Python file and process operations, and `mc.execute()` can run Minecraft commands from the server command source.

For public or shared servers, restrict `/pythonmc` command access to trusted operators only.

Server Side Only

PythonMC is intended for server-side scripting. Clients do not need to install the mod when connecting to a server that uses it, unless your modpack or server setup requires matching mod lists.

Troubleshooting

If scripts do not start:

- Run `/pythonmc status`. - Confirm Python 3.8+ is installed. - Confirm `python3` or `python` works from the same environment that launches the Minecraft server. - Set `-Dpythonmc.python=/path/to/python` if needed. - Check the server log for messages tagged with `pythonmc` or `[python]`.

If script changes do not apply:

- Make sure the file is in `config/pythonmc/scripts`. - Make sure the filename ends in `.py`. - Make sure the filename does not start with `_`. - Run `/pythonmc reload`. - Check the server log for Python traceback output.