进阶功能:MODSDK(PythonRPC)包的使用与交互
从客户端开发来看,这套方案沿用中国版 Add-On 的原生 MOD SDK 写法。资源包和行为包仍按 Add-On 的目录结构组织,客户端脚本照常注册系统,用 NotifyToServer 发出自定义事件,用 ListenForEvent 监听引擎事件和服务端回复。
在 Paper + Geyser 部署中,由 Paper 插件实现原生 MOD SDK 服务端系统负责的玩法逻辑,包括接收客户端事件、处理请求和发送回复。Geyser 和配套 Floodgate 负责转发 PythonRPC 消息,两端仍按约定的命名空间、系统名、事件名和参数通信。
客户端进服后向 Paper 查询提示键 welcome,再从资源包取出「欢迎进入服务器!PythonRPC 联通成功。」示例用 SetTipMessage 在快捷栏上方显示文案,同时用 SetLeftCornerNotify 在本机左上角显示聊天通知。SetTipMessage 接口文档、SetLeftCornerNotify 接口文档
示例项目
在 GeyserDemo 的 pythonrpc-demo/ 子目录可以找到两个包和完整的 Paper 插件。行为包清单通过资源包的 header.uuid 和版本声明依赖。GeyserDemo 仓库
中国版 MOD SDK 脚本仅支持 Python 2.7。示例中的 basestring 和 unicode 用来处理 2.7 中的字符串类型。
pythonrpc-demo/
├── packs/
│ ├── behavior_packs/
│ │ └── RpcDemo_BP/
│ │ ├── manifest.json
│ │ └── RpcDemoScripts/
│ │ ├── __init__.py
│ │ ├── modMain.py
│ │ └── client.py
│ └── resource_packs/
│ └── RpcDemo_RP/
│ ├── manifest.json
│ └── modconfigs/
│ └── geyser_rpc_demo.json
├── src/main/
│ ├── java/com/example/rpcdemo/
│ │ ├── RpcDemoPlugin.java
│ │ └── RpcPacket.java
│ └── resources/plugin.yml
└── build.gradle
使用前文的 Paper 1.21.11、Velocity、布吉岛版 Geyser 和配套 Floodgate。Velocity 端启用 send-floodgate-data: true,Velocity 与 Paper 使用同一份 key.pem。项目部署、配套 Geyser、配套 Floodgate
两端怎样交换事件
| 方向 | 命名空间 | 系统名 | 事件 | 参数 |
|---|---|---|---|---|
| 客户端 → Paper | RpcDemo | RpcDemoClientSystem | QueryServerMessage | requestId |
| Paper → 客户端 | RpcDemo | RpcDemoServerSystem | ServerMessage | requestId、tipKey |
modMain.py 从 @Mod.InitClient() 注册 RpcDemoClientSystem,类路径为 RpcDemoScripts.client.RpcDemoClient。client.py 先注册 ServerMessage 的监听,然后在 OnLocalPlayerStopLoading 回调里执行下方代码。这个事件在出生点地形加载完成时触发。Python 脚本开发入门、世界事件文档、NotifyToServer 接口文档
data = self.CreateEventData()
data["requestId"] = "demo-1"
self.NotifyToServer("QueryServerMessage", data)
Paper 的 RpcDemoPlugin 用 Bukkit Messenger 监听 floodgate:netease。RpcPacket 解码请求,核对事件名和 requestId。回包沿用同一个 requestId,并指定 tipKey 为 welcome。下面用 JSON 表示回包结构。插件会将它编码为 MessagePack,再用 GZIP 压缩,通过配套 Floodgate 的 neteaseCustomChannel 发回该玩家。
[
"ModEventS2C",
["RpcDemo", "RpcDemoServerSystem", "ServerMessage", {"requestId": "demo-1", "tipKey": "welcome"}],
null
]
客户端显示资源包里的提示
在资源包的 modconfigs/geyser_rpc_demo.json 中用 welcome 作为文案的键。
{
"welcome": "欢迎进入服务器!PythonRPC 联通成功。"
}
client.py 核对 requestId 后按 tipKey 查找文案,并把 unicode 转成 UTF-8 编码的 str。用本地玩家 ID 创建 Game 组件显示快捷栏提示,再用 GetLevelId() 创建 TextNotifyClient 组件显示本机的聊天通知。print 用于记录脚本日志。GetModConfigJson 接口文档、客户端 API 索引
def on_reply(self, args):
if args.get("requestId") != "demo-1":
return
tip_key = args.get("tipKey")
if not isinstance(tip_key, basestring):
return
tips = clientApi.GetModConfigJson("modconfigs/geyser_rpc_demo.json")
text = tips.get(tip_key)
if not isinstance(text, basestring) or not text:
print("[RpcDemo] Tip missing in resource pack: {}".format(tip_key))
return
if isinstance(text, unicode):
text = text.encode("utf-8")
factory = clientApi.GetEngineCompFactory()
game = factory.CreateGame(clientApi.GetLocalPlayerId())
if game.SetTipMessage(text):
print("[RpcDemo] Displayed tip: {}".format(tip_key))
else:
print("[RpcDemo] Could not display tip: {}".format(tip_key))
notify = factory.CreateTextNotifyClient(clientApi.GetLevelId())
if not notify.SetLeftCornerNotify("[RpcDemo] " + text):
print("[RpcDemo] Could not show chat notice: {}".format(tip_key))
部署与联调
- 安装 JDK 21。将配套
floodgate-spigot.jar放入pythonrpc-demo/libs/,在该项目目录运行.\gradlew.bat build。Linux 或 macOS 使用sh ./gradlew build。 - 将生成的
build/libs/pythonrpc-demo-1.0.0.jar放入 Paper 子服的plugins/。启动 Paper,检查RpcDemo和floodgate是否加载成功。 - 把示例
packs/中的RpcDemo_RP/、RpcDemo_BP/分别放进网易服务器预下载模板的resource_packs/、behavior_packs/,一起打包,上传到服务器编辑界面并自测。通过自测后下载加密 ZIP,部署到 Geyser 的packs/Encryption/。打包与部署步骤 - 用目标中国版客户端进服,检查快捷栏上方的提示和左上角带
[RpcDemo]前缀的聊天通知。可以对照 Paper 日志QueryServerMessage -> ServerMessage (demo-1)和脚本日志[RpcDemo] Displayed tip: welcome。退出并重新进服即可再次触发。
| 现象 | 排查位置 |
|---|---|
客户端没有输出 Client system ready | 检查预下载中是否包含行为包,以及 modMain.py、RegisterSystem 的类路径。 |
| 客户端脚本已启动,Paper 没有记录请求 | 检查配套 Floodgate、代理的数据转发、频道注册和 C2S 事件名。 |
| Paper 已回包,客户端提示资源包里缺少文案 | 检查资源包是否随包体加载,核对 modconfigs/geyser_rpc_demo.json 路径和 welcome 键。 |
| 更新包后文案仍是旧版 | 更新资源包版本及行为包中的依赖版本,再核对预下载版本和 Geyser 加载的加密包。 |