Python MC Mod

PythonMC

PythonMC — это серверный мод для Fabric, добавляющий в Minecraft 1.21.1 лёгкое скриптование на Python. Он позволяет владельцам серверов писать простые скрипты на Python для типовой автоматизации, сообщений игрокам, серверных событий и поведения по командам без перекомпиляции мода.

Возможности

• Загружает скрипты Python из папки конфигурации сервера.
• Автоматически запускает и управляет локальным хостом скриптов Python 3.8+.
• Предоставляет события жизненного цикла сервера, тиков и подключения игроков.
• Открывает небольшой API для логирования, широковещательных сообщений, личных сообщений и выполнения серверных команд.
• Включает админ-команды /pythonmc для статуса, перезагрузок, перезапусков, пользовательских событий и быстрых сниппетов Python.
• При первом запуске поставляется с примером скрипта.

Требования

• Minecraft 1.21.1
• Fabric Loader 0.18.4 или новее
• Fabric API
• Java 21
• Python 3.8 или новее, установленный на сервере Python должен быть доступен как python3 или python в PATH сервера. Если Python установлен в другом месте, задайте одно из этого перед запуском Minecraft:

-Dpythonmc.python=/path/to/python

или:

PYTHONMC_PYTHON=/path/to/python

Установка

1. Установите Fabric Loader для Minecraft 1.21.1.
2. Установите Fabric API.
3. Поместите jar-файл PythonMC в папку mods сервера.
4. Убедитесь, что Python 3.8+ установлен на машине, запускающей сервер.
5. Запустите сервер один раз. PythonMC создаст эту папку:

config/pythonmc/scripts

Он также создаст стартовый скрипт:

config/pythonmc/scripts/main.py

Написание скриптов

Скрипты — это обычные файлы .py внутри:

config/pythonmc/scripts

Файлы, имена которых начинаются с _, игнорируются. После редактирования скриптов перезагрузите их в игре или из консоли сервера:

/pythonmc reload

Базовый пример:

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.")

API скриптов

Импортируйте встроенный API так:

import pythonmc_api as mc

Доступные функции:

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

mc.execute(command) выполняет команду сервера Minecraft от имени источника команд сервера. Используйте осторожно.

События

PythonMC вызывает функции в ваших скриптах при наступлении соответствующих событий. Поддерживаемые обработчики событий:

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): ...

Объект ctx содержит данные события. Он поддерживает как доступ в стиле словаря, так и .get():

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

Общие поля событий игрока:

name
uuid

Общие поля событий сервера:

players
max_players
tick
scripts_dir

Команды

Все команды требуют уровень разрешений 4.

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

Подробности команд:

• /pythonmc status показывает, запущен ли хост Python и откуда загружаются скрипты.
• /pythonmc start запускает хост скриптов Python, если он остановлен.
• /pythonmc stop останавливает хост скриптов Python.
• /pythonmc restart перезапускает хост скриптов Python.
• /pythonmc reload перезагружает скрипты из config/pythonmc/scripts.
• `/pythonmc py ` выполняет сниппет Python в процессе хоста.
• /pythonmc event <event_name> отправляет пользовательское событие скриптам. Пример пользовательского события:

import pythonmc_api as mc


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

Затем выполните:

/pythonmc event maintenance

Замечания по безопасности

Скрипты PythonMC выполняются на машине сервера с правами процесса сервера Minecraft. Устанавливайте или пишите только те скрипты, которым доверяете. Скрипт Python может выполнять обычные файловые и процессные операции Python, а mc.execute() может запускать команды Minecraft от имени источника команд сервера. Для публичных или общих серверов ограничьте доступ к команде /pythonmc только доверенными операторами.

Только для серверной стороны

PythonMC предназначен для серверного скриптования. Клиентам не нужно устанавливать мод при подключении к серверу, который его использует, если только ваш модпак или настройка сервера не требуют совпадающих списков модов.

Решение проблем

Если скрипты не запускаются:

• Выполните /pythonmc status.
• Убедитесь, что установлен Python 3.8+.
• Убедитесь, что python3 или python работает в том же окружении, из которого запускается сервер Minecraft.
• При необходимости задайте -Dpythonmc.python=/path/to/python.
• Проверьте лог сервера на сообщения с тегом pythonmc или [python]. Если изменения скриптов не применяются:
• Убедитесь, что файл находится в config/pythonmc/scripts.
• Убедитесь, что имя файла заканчивается на .py.
• Убедитесь, что имя файла не начинается с _.
• Выполните /pythonmc reload.
• Проверьте лог сервера на вывод трассировки Python.