PythonMC
PythonMC 是一个面向 Minecraft 1.21.1 的服务端 Fabric 模组,为游戏增添了轻量级的 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 回溯输出。
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:
-Dpythonmc.python=/path/to/python
or:
PYTHONMC_PYTHON=/path/to/python
Installation
- Install Fabric Loader for Minecraft 1.21.1.
- Install Fabric API.
- Put the PythonMC jar in the server
mods folder.
- Make sure Python 3.8+ is installed on the machine running the server.
- Start the server once.
PythonMC will create this folder:
config/pythonmc/scripts
It will also create a starter script:
config/pythonmc/scripts/main.py
Writing Scripts
Scripts are normal .py files inside:
config/pythonmc/scripts
Files whose names start with _ are ignored. After editing scripts, reload them in-game or from the server console:
/pythonmc reload
Basic example:
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:
import pythonmc_api as mc
Available functions:
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:
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():
def on_player_join(ctx):
player_name = ctx["name"]
player_uuid = ctx.get("uuid")
Common player event fields:
name
uuid
Common server event fields:
players
max_players
tick
scripts_dir
Commands
All commands require permission level 4.
/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:
import pythonmc_api as mc
def on_event(event_name, ctx):
if event_name == "maintenance":
mc.broadcast("Server maintenance is starting soon.")
Then run:
/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.
评论 0
登录后参与评分
还没有评论,来抢沙发吧