
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
安装
- 为 Minecraft 1.21.1 安装 Fabric Loader。
- 安装 Fabric API。
- 将 PythonMC 的 jar 放入服务器的
mods文件夹。 - 确保运行服务器的机器上安装了 Python 3.8+。
- 启动一次服务器。
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 回溯输出。
正在加载版本记录…
正在加载评论…
评论在新手盒子客户端中发表,这里同步展示。