Python MC 模组

Python MC 模组

这个模组为fabric添加了python编程功能。

管理

PythonMC

PythonMC 是一个服务端 Fabric 模组,为 Minecraft 1.21.1 添加轻量级的 Python 脚本功能。

它让服务器管理员能够编写简单的 Python 脚本,用于常见的自动化、玩家消息、服务器事件以及由命令驱动的行为,而无需重新编译模组。

功能特性

  • 从服务器配置文件夹加载 Python 脚本。
  • 自动启动并管理一个本地 Python 3.8+ 脚本宿主。
  • 提供服务器生命周期、刻(tick)和玩家连接事件。
  • 提供一个小型 API,用于日志记录、广播、私聊消息和服务器命令执行。
  • 包含 /pythonmc 管理员命令,用于查看状态、重载、重启、自定义事件以及执行快速 Python 片段。
  • 首次启动时附带一个示例脚本。

环境要求

  • Minecraft 1.21.1
  • Fabric Loader 0.18.4 或更高版本
  • Fabric API
  • Java 21
  • 服务器上安装了 Python 3.8 或更高版本

Python 必须在服务器的 PATH 中可通过 python3 或 python 调用。

如果 Python 安装在其它位置,请在启动 Minecraft 前设置以下任一内容:

-Dpythonmc.python=/path/to/python

或:

PYTHONMC_PYTHON=/path/to/python

安装

  1. 为 Minecraft 1.21.1 安装 Fabric Loader。
  2. 安装 Fabric API。
  3. 将 PythonMC 的 jar 放入服务器的 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 code> 在宿主进程中运行一段 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+。
  • 确认从启动 Minecraft 服务器的同一环境中 python3 或 python 可以正常工作。
  • 如有需要,设置 -Dpythonmc.python=/path/to/python。
  • 检查服务器日志中带有 pythonmc 或 [python] 标签的消息。

如果脚本更改未生效:

  • 确保文件位于 config/pythonmc/scripts 中。
  • 确保文件名以 .py 结尾。
  • 确保文件名不以 _ 开头。
  • 运行 /pythonmc reload。
  • 检查服务器日志中的 Python 回溯输出。